gframework

gframework

gframework is a production-ready Go microservices framework providing essential building blocks for scalable backend services: an Echo v5 HTTP server, Keycloak/JWT authentication, PostgreSQL, Redis/Valkey messaging, S3-compatible object storage, and coordinated service lifecycle management.

📦 Installation

go get github.com/andyle182810/gframework

🧩 Packages

🚀 Quick Start

A minimal service wired through the runner (see examples/minimal-api for the full program):

package main

import (
	"net/http"
	"time"

	"github.com/andyle182810/gframework/httpserver"
	"github.com/andyle182810/gframework/runner"
	"github.com/labstack/echo/v5"
)

func main() {
	server := httpserver.New(&httpserver.Config{
		Host:        "0.0.0.0",
		Port:        8080,
		BodyLimit:   "10M",
		GracePeriod: 10 * time.Second,
	})

	server.Root.GET("/health", func(c *echo.Context) error {
		return c.JSON(http.StatusOK, map[string]string{"status": "ok"})
	})

	// Blocks until SIGINT/SIGTERM or a service failure; exits non-zero on error.
	runner.New(
		runner.WithCoreService(server),
	).Run()
}

Services implement the runner.Service interface (Start(ctx) error, Stop() error, Name() string). Register databases, caches, and queues with WithInfrastructureService — they start first and stop last; register HTTP servers and subscribers with WithCoreService. If you need to manage signals or exit codes yourself (or drive the runner from a test), use RunContext(ctx) error instead of Run().

🔐 Security configuration

The framework applies secure defaults, but several knobs are deployment-specific — review these before going to production:

JWT validation (middleware.JWTWithConfig): algorithm pinning is on by default (asymmetric algorithms only — HS* is rejected). Set Issuer and Audiences so tokens minted by other realms or for other services are rejected:

kf, _ := jwks.New(ctx, []string{"https://auth.example.com/realms/my-realm/protocol/openid-connect/certs"})

config := middleware.DefaultJWTConfig()
config.Keyfunc = kf
config.Issuer = "https://auth.example.com/realms/my-realm"
config.Audiences = []string{"my-service"}

e.Use(middleware.JWTWithConfig(config))

HTTP server timeouts (httpserver, metricserver): when unset, ReadHeaderTimeout 10s, ReadTimeout 30s, WriteTimeout 30s, IdleTimeout 120s. Override explicitly for streaming or long-polling endpoints.

CORS: EnableCors with an empty AllowOrigins allows every origin (and logs a warning). Always set AllowOrigins in production.

Internal service-to-service auth: protect internal endpoints with middleware.InternalAuth(kf, allowedClients); on the calling side, use httpclient with WithInternalAuthHeader() (the internal header is not sent by default — see Breaking changes below).

Error responses: never enable ErrorHandlerConfig.IncludeInternalErrors in production — it exposes internal error strings to clients.

Metrics: metricserver has no authentication. Bind it to an internal interface and keep it off the public network.

Request logs: values of sensitive query parameters (token, code, api_key, password, …) are automatically redacted.

Dependency scanning: CI runs govulncheck. Known remaining findings are confined to github.com/docker/docker via testcontainers (test-only dependency, no fixed release at the time of writing).

🧪 Testing

The framework ships testcontainers helpers for integration tests (Docker required):

func TestWithPostgres(t *testing.T) {
	container := testutil.SetupPostgresContainer(t)

	db, err := postgres.New(&postgres.Config{URL: container.ConnectionString()})
	require.NoError(t, err)
	// Run tests...
}

Run everything:

make test       # go test ./... (no cache)
make lint       # go vet + golangci-lint v2 (fmt + run)

💡 Examples

🛠️ Error handling conventions

• Sentinel errors are package-level variables with the Err prefix (e.g. ErrConfigNil)
• Errors are wrapped with fmt.Errorf("...: %w", err) for errors.Is/errors.As
• HTTP errors use echo.HTTPError and are rendered by middleware.ErrorHandler

📚 Key dependencies

• Echo v5 — HTTP framework
• pgx v5 — PostgreSQL driver
• go-redis v9 — Redis/Valkey client
• Watermill — message streaming
• golang-jwt v5 + MicahParks/keyfunc — JWT/JWKS
• zerolog — structured logging
• testcontainers-go — integration testing

📬 Support

For bugs, questions, or feature requests, open an issue: 👉 https://github.com/andyle182810/gframework/issues

📄 License

gframework is licensed under the MIT License. See LICENSE for details.