gorest Documentation

gorest supports various JWT signing algorithms. Use the following OpenSSL commands to generate the necessary keys.

HMAC (HS) Keys

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

ECDSA (ES) Key Pairs

ES256 (P-256)

openssl ecparam -name prime256v1 -genkey -noout -out private-key.pem
openssl ec -in private-key.pem -pubout -out public-key.pem

ES384 (secp384r1)

openssl ecparam -name secp384r1 -genkey -noout -out private-key.pem
openssl ec -in private-key.pem -pubout -out public-key.pem

ES512 (secp521r1)

openssl ecparam -name secp521r1 -genkey -noout -out private-key.pem
openssl ec -in private-key.pem -pubout -out public-key.pem

EdDSA (Ed25519)

openssl genpkey -algorithm Ed25519 -out private-key.pem
openssl pkey -in private-key.pem -pubout -out public-key.pem

RSA (RS) Key Pairs

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

Running Tests

To run tests with coverage, set the required environment variables for the test environment:

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 ./...

Cross-Compilation

You can build binaries for different operating systems and architectures using the following commands:

Linux (ARM64/AMD64)

GOOS=linux GOARCH=arm64 go build
GOOS=linux GOARCH=amd64 go build

macOS (ARM64/AMD64)

GOOS=darwin GOARCH=arm64 go build
GOOS=darwin GOARCH=amd64 go build

Windows (ARM64)

GOOS=windows GOARCH=arm64 go build

gorest is a RESTful API starter kit built with Golang and the Gin framework. To start building, follow these steps:

1. Configure Environment Variables: Locate the .env.sample file in the root directory. Rename it to .env and configure the variables according to your specific setup (database credentials, JWT secrets, etc.).
2. Install Databases: Ensure you have a supported database installed (MySQL, PostgreSQL, SQLite3, Redis, or MongoDB). Note that for Two-Factor Authentication (2FA), you need both a relational database and a Redis instance.
3. Set up Go Environment: Ensure you have a compatible Go version installed (see Go Requirements).
4. Study Examples:
   • Use example2 for projects requiring interface-driven design, modularity, and testability.
   • Use example for rapid prototyping and simplicity.

# Example: Renaming the sample env file
cp .env.sample .env

The gorest Sentry middleware integrates logrus with sentry-go using a custom sentryCombinedHook.

Key Behaviors:

• Immediate Capture: The hook captures issues before delegating to the standard Sentry logrus hook. This ensures that Fatal and Panic level logs are captured before the process terminates.
• Automatic Flushing: For Fatal or Panic log levels, the hook automatically triggers a Flush (up to 2 seconds) to ensure the event is delivered before the process exits.
• Contextual Enrichment: If a log entry contains a context (e.g., via log.WithContext(ctx)), the hook attempts to extract a Sentry Hub from that context. This allows per-request tags and request-specific data to be attached to the error report.
• Data Mapping: Logrus fields are automatically converted to Sentry tags. If a field contains an error (specifically using the logrus.ErrorKey), the hook captures it as a Sentry Exception instead of a simple message.

To run the web service, use a router setup function (e.g., router.SetupRouter(configure)) to generate an http.Handler. Attach this handler to a standard http.Server. To ensure the application shuts down cleanly (closing database connections and finishing active requests), use gserver.GracefulShutdown. This function takes the server instance, a timeout duration, a completion channel, and a cleanup function (like gdb.CloseAllDB).

// 1. Setup Router
r, err := router.SetupRouter(configure)

// 2. Configure HTTP Server
srv := &http.Server{
	Addr:    configure.Server.ServerHost + ":" + configure.Server.ServerPort,
	Handler: r,
	ReadTimeout: 30 * time.Second,
}

// 3. Setup Graceful Shutdown
done := make(chan struct{})
go func() {
	err := gserver.GracefulShutdown(srv, 30*time.Second, done, gdb.CloseAllDB)
	if err != nil {
		fmt.Println(err)
	}
}()

// 4. Start Server
if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
	fmt.Printf("server error: %v\n", err)
}

// 5. Wait for shutdown
<-done

To run the API, you need to set up a router (typically using router.SetupRouter(configure)) and attach it to a standard http.Server.

To ensure the server handles termination signals correctly and closes database connections, use gserver.GracefulShutdown. This function requires the server instance, a shutdown timeout, a completion channel, and a cleanup function (like gdatabase.CloseAllDB).

// 1. Setup Router
r, err := router.SetupRouter(configure)
if err != nil {
	return err
}

// 2. Configure HTTP Server
srv := &http.Server{
	Addr:    configure.Server.ServerHost + ":" + configure.Server.ServerPort,
	Handler: r,
	ReadTimeout:       30 * time.Second,
	ReadHeaderTimeout: 5 * time.Second,
	WriteTimeout:      5 * time.Second,
	IdleTimeout:       60 * time.Second,
}

// 3. Setup Graceful Shutdown
done := make(chan struct{})
const shutdownTimeout = 30 * time.Second

go func() {
	err := gserver.GracefulShutdown(
		srv,
		shutdownTimeout,
		done,
		gdatabase.CloseAllDB,
	)
	if err != nil {
		fmt.Println(err)
	}
}()

// 4. Start Server
if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
	fmt.Printf("server error: %v\n", err)
}

// 5. Wait for shutdown
<-done