GOE Framework

Build production Go applications in minutes, not days.

Dependency injection, HTTP, databases, caching, jobs, and distributed locking — wired together and ready to go.

Documentation · Examples · Configuration · Contributing

Why GOE?

Most Go projects start the same way: wiring up a logger, a config loader, an HTTP server, a database connection, graceful shutdown — before writing a single line of business logic.

GOE handles all of that. It combines Uber Fx for dependency injection with GoFiber v3 for HTTP, then layers on the infrastructure modules most applications need. Everything is interface-driven, concurrency-safe, and testable out of the box.

Quick Start

go get go.oease.dev/goe/v2

package main

import (
    "github.com/gofiber/fiber/v3"
    "go.oease.dev/goe/v2"
    "go.oease.dev/goe/v2/contract"
    "go.oease.dev/goe/v2/webresult"
)

func main() {
    _ = goe.New(goe.Options{
        WithHTTP: true,
        Invokers: []any{registerRoutes},
    })
    goe.Run() // blocks until SIGINT/SIGTERM
}

func registerRoutes(app contract.HTTPKernel, log contract.Logger) {
    app.App().Get("/", func(c fiber.Ctx) error {
        return c.SendString("Hello from GOE!")
    })

    app.App().Get("/health", func(c fiber.Ctx) error {
        return webresult.SendSucceed(c, fiber.Map{"status": "healthy"})
    })

    log.Info("Routes registered")
}

go run main.go
# → http://localhost:8080

See the full examples/ directory for real-world patterns including REST APIs with MongoDB, custom modules, and production configuration.

Features

Core

	Feature	What You Get
🔌	Dependency Injection	Uber Fx — type-safe, automatic resolution, lifecycle hooks
🌐	HTTP Server	GoFiber v3 — fast routing, middleware, request logging
📝	Logging	Uber Zap — structured JSON for production, colored console for dev
⚙️	Configuration	.env files with environment layering, type-safe accessors

Data

	Feature	What You Get
🗄️	SQL Databases	GORM with MySQL, PostgreSQL, SQLite, SQL Server. Multiple named connections
🍃	MongoDB	Native driver with pooling, transactions, helper utilities, and a fluent migration system
💾	Caching	Unified interface across 10+ backends — Redis, Memory, S3, DynamoDB, Badger, and more

Infrastructure

	Feature	What You Get
📋	Job System	Redis-backed background processing with scheduling, retries, and dead letter queues
🔐	Distributed Lock	Redlock algorithm — single instance, Sentinel, or Cluster modes
🩺	Health & Metrics	Built-in health checks and OpenTelemetry integration

Design

	Feature	What You Get
🧩	Module System	Managed lifecycles (OnStart/OnStop), config validation, clean boundaries
🛡️	Contracts	Interface-driven design — swap implementations, mock in tests
⚡	Concurrency Safe	Singleflight cache protection, atomic operations, race-free by default
🧬	Go 1.26 Baseline	Modern idioms throughout (generics, WaitGroup.Go, iterators); builds get the Green Tea GC and container-aware GOMAXPROCS automatically

Enabling Modules

Turn on what you need:

goe.New(goe.Options{
    WithHTTP:    true,  // HTTP server (Fiber v3)
    WithCache:   true,  // Caching (memory, Redis, Badger, bbolt + custom drivers)
    WithDB:      true,  // SQL database (GORM)
    WithMongoDB: true,  // MongoDB with connection pooling
    WithMigrate: true,  // MongoDB schema migrations
    WithJob:     true,  // Background job processing
    WithLock:    true,  // Distributed mutex (Redlock)
})

Configuration

GOE loads config from multiple sources, in priority order:

Priority	Source	Purpose
1	.env	Base defaults
2	.local.env	Local dev overrides (gitignored)
3	.{GOE_ENV}.env	Environment-specific (prod, staging)
4	System ENV	Deployment overrides — highest priority

See .example.env for every available option with documentation.

Or configure in Go

The HTTP, cache, job, lock, MongoDB, and migration modules can be configured entirely in code, with no .env required:

import (
    goecache "go.oease.dev/goe/v2/core/cache"
    goehttp "go.oease.dev/goe/v2/core/http"
    goejob "go.oease.dev/goe/v2/core/job"
)

goe.New(goe.Options{
    // Passing options enables the module — WithHTTP: true is not needed
    HTTP: []goehttp.Option{
        goehttp.WithPort(8080),
        goehttp.WithBodyLimit(16 << 20),
        goehttp.WithCertFile("server.crt"),   // TLS, which has no env equivalent
        goehttp.WithCertKeyFile("server.key"),
    },
    Cache: []goecache.Option{
        goecache.WithDriver("redis"),
        goecache.WithTTL(30 * time.Minute),
    },
    Job: []goejob.Option{
        goejob.WithConcurrency(10),
        goejob.WithDefaultQueue("critical"),
    },
})

Options sit above the environment: a field set in code wins, and every field left alone still reads from .env, so adding options to an existing app changes nothing else. For HTTP, every field of fiber.Config and fiber.ListenConfig is available as With<FieldName>; for cache, job, and lock every setting has a matching option — except credentials. *_REDIS_USERNAME, *_REDIS_PASSWORD and credential-capable URLs stay environment-only by design (lock's WithRedisURL even rejects URLs embedding user:pass), so secrets never end up in source while still applying to endpoints chosen in code. See CONFIGURATION.md and examples/06-code-first-config.

Behind a CDN

Trust your CDN's edge IPs so Ctx.IP() reports the real client rather than the edge node, using published ranges:

import "go.oease.dev/goe/v2/cdntrust"

cdnOpts, err := cdntrust.Options(ctx, cdntrust.Cloudflare, cdntrust.Fastly)
if err != nil {
    log.Fatalf("cdn trust: %v", err) // don't start with an unknown trust set
}

goe.New(goe.Options{HTTP: append(cdnOpts, goehttp.WithPort(8080))})

Cloudflare, Fastly and BunnyCDN are supported. The fetch happens once at boot and is entirely optional — nothing in GOE imports cdntrust, so it costs you nothing unless you use it.

Documentation

Upgrading? See MIGRATION.md for breaking changes.

Full documentation is available on DeepWiki:

deepwiki.com/oeasenet/goe

Contributing

Contributions are welcome.

1. Fork the repository and create a feature branch
2. Run go mod download to install dependencies
3. Make your changes and ensure tests pass:

   go test -race ./...
   
   # Integration tests need Redis and a single-node MongoDB replica set
   # (the migrator uses transactions, which standalone MongoDB rejects):
   make test_integration_full   # starts services, runs, tears down

4. Open a pull request against v2 with a clear description

Found a bug or have a question? Open an issue.

License

MIT — see LICENSE for details.