Skip to content

Latest commit

 

History

History
283 lines (210 loc) · 8.13 KB

README.md

File metadata and controls

283 lines (210 loc) · 8.13 KB
Raw

gorest | RESTful API Starter kit

CodeQL Go Linter Codecov Go Reference Go Report Card CodeFactor codebeat badge MIT license Contributor Covenant

gorest is a starter kit, written in Golang with Gin framework, for rapid prototyping and developing a RESTful API. The source code is released under the MIT license and is free for any personal or commercial project.

Versioning

1.x.y

1: production-ready

x: breaking changes

y: new functionality or bug fixes in a backwards compatible manner

Important

Version 1.6.x contains breaking changes!

Note: For version 1.4.5 (obsolete): v1.4.5

For all projects, it is recommended to use version 1.6.x or higher.

Requirement

Go 1.20+

Supported databases

  • MySQL
  • PostgreSQL
  • SQLite3
  • Redis
  • MongoDB

Note: gorest uses GORM as its ORM

Features

  • built on top of Gin
  • option to enable encryption at rest for user private information
  • use the supported databases without writing any extra configuration files
  • environment variables using GoDotEnv
  • CORS policy
  • basic auth
  • two-factor authentication
  • JWT using golang-jwt/jwt
  • password hashing using Argon2id with optional secret (NIST 800-63B recommends using a secret value of at least 112 bits)
  • JSON protection from hijacking
  • simple firewall (whitelist/blacklist IP)
  • email validation (pattern + MX lookup)
  • email verification (sending verification code)
  • forgotten password recovery
  • render HTML templates
  • forward error logs and crash reports to sentry.io
  • handle authentication tokens on client devices' cookies
  • logout (individually enable option - delete tokens from cookies, ban active tokens)
  • rate limiting (IP-based)
  • option to validate origin of the request
  • super easy to learn and use - lots of example codes

Supported JWT signing algorithms

  • HS256: HMAC-SHA256
  • HS384: HMAC-SHA384
  • HS512: HMAC-SHA512
  • ES256: ECDSA Signature with SHA-256
  • ES384: ECDSA Signature with SHA-384
  • ES512: ECDSA Signature with SHA-512
  • RS256: RSA Signature with SHA-256
  • RS384: RSA Signature with SHA-384
  • RS512: RSA Signature with SHA-512

Procedures to generate HS256, HS384, HS512 keys using openssl:

  • HS256: openssl rand -base64 32
  • HS384: openssl rand -base64 48
  • HS512: openssl rand -base64 64

Procedures to generate public-private key pair using openssl:

ECDSA

ES256

  • prime256v1: X9.62/SECG curve over a 256 bit prime field, also known as P-256 or NIST P-256
  • widely used, recommended for general-purpose cryptographic operations
openssl ecparam -name prime256v1 -genkey -noout -out private-key.pem
openssl ec -in private-key.pem -pubout -out public-key.pem

ES384

  • secp384r1: NIST/SECG curve over a 384 bit prime field
openssl ecparam -name secp384r1 -genkey -noout -out private-key.pem
openssl ec -in private-key.pem -pubout -out public-key.pem

ES512

  • secp521r1: NIST/SECG curve over a 521 bit prime field
openssl ecparam -name secp521r1 -genkey -noout -out private-key.pem
openssl ec -in private-key.pem -pubout -out public-key.pem

RSA

RS256

openssl genpkey -algorithm RSA -out private-key.pem -pkeyopt rsa_keygen_bits:2048
openssl rsa -in private-key.pem -pubout -out public-key.pem

RS384

openssl genpkey -algorithm RSA -out private-key.pem -pkeyopt rsa_keygen_bits:3072
openssl rsa -in private-key.pem -pubout -out public-key.pem

RS512

openssl genpkey -algorithm RSA -out private-key.pem -pkeyopt rsa_keygen_bits:4096
openssl rsa -in private-key.pem -pubout -out public-key.pem

Example docker compose file

# syntax=docker/dockerfile:1

version: '3.9'
name: go
services:
  goapi:
    image: golang:latest
    container_name: goapi
    working_dir: /app/
    restart: unless-stopped:10s
    command: /app/goapi
    ports:
      - '127.0.0.1:8000:8999'
    volumes:
      - ./app:/app/

Start building

Please study the .env.sample file. It is one of the most crucial files required to properly set up a new project. Please rename the .env.sample file to .env, and set the environment variables according to your own instance setup.

Tutorials:

For version 1.6.x, please check the project in example

For version 1.4.x and 1.5.x, Wiki (obsolete)

  • convention over configuration
import (
  "github.com/gin-gonic/gin"

  gconfig "github.com/pilinux/gorest/config"
  gcontroller "github.com/pilinux/gorest/controller"
  gdatabase "github.com/pilinux/gorest/database"
  gmiddleware "github.com/pilinux/gorest/lib/middleware"
)
  • install a relational (SQLite3, MySQL or PostgreSQL), Redis, or Mongo database
  • for 2FA, a relational + a redis database is required
  • set up an environment to compile the Go codes (a quick tutorial for any Debian based OS)
  • install git
  • check the Wiki and example for tutorials and implementations

Note: For MySQL driver, please check issue: 7

Note For SQLite3:

  • DBUSER, DBPASS, DBHOST and DBPORT environment variables are not required.
  • DBNAME must contain the full or relative path of the database file name; i.e,
/user/location/database.db

or,

./database.db

Debugging with Error Codes

package file error code range
controller login.go 1011 - 1012
controller twoFA.go 1041 - 1044
database dbConnect.go 150 - 155, 161
handler auth.go 1001 - 1003
handler login.go 1013 - 1014
handler logout.go 1016
handler passwordReset.go 1021 - 1030
handler twoFA.go 1051 - 1056
handler verification.go 1061 - 1065
service common.go 401 - 406
service security.go 501

Development

For testing:

export TEST_ENV_URL="https://s3.nl-ams.scw.cloud/ci.config/github.action/gorest.pilinux/.env"
export TEST_INDEX_HTML_URL="https://s3.nl-ams.scw.cloud/ci.config/github.action/gorest.pilinux/index.html"
export TEST_KEY_FILE_LOCATION="https://s3.nl-ams.scw.cloud/ci.config/github.action/gorest.pilinux"
export TEST_SENTRY_DSN="please_set_your_sentry_DSN_here"

go test -v -cover ./...

Contributing

Please see CONTRIBUTING to join this amazing project.

Code of conduct

Please see this document.

License

© Mahir Hasan 2019 - 2024

Released under the MIT license