README.md

Forge

A Go framework for backend services, with dependency injection, an extension system, and observability built in.

Forge™ is a backend framework, and Forge Cloud™ is its AI cloud offering, maintained by XRAPH™.

Quick start

go install github.com/xraph/forge/cmd/forge@latest
forge --version

forge init my-app
forge dev

A minimal service:

package main

import "github.com/xraph/forge"

func main() {
    app := forge.NewApp(forge.AppConfig{
        Name:        "my-app",
        Version:     "1.0.0",
        Environment: "development",
        HTTPAddress: ":8080",
    })

    router := app.Router()
    router.GET("/", func(ctx forge.Context) error {
        return ctx.JSON(200, map[string]string{
            "message": "Hello, Forge!",
        })
    })

    // Blocks until SIGINT or SIGTERM.
    app.Run()
}

Every app serves three endpoints without configuration: /_/info for application metadata, /_/metrics for Prometheus, and /_/health for health checks.

What you get

The core framework handles the parts most services need before they can do anything interesting:

• A type-safe dependency injection container with service lifecycles
• An HTTP router with trie-based path matching and middleware support
• Middleware for auth, CORS, logging and rate limiting
• Configuration from YAML, JSON or TOML, overridable by environment variables
• Structured logging, Prometheus metrics and distributed tracing
• Health checks that discover and report themselves
• Graceful startup and shutdown, so SIGTERM cleans up rather than drops work

The CLI scaffolds projects, generates handlers and services, runs migrations, and serves your app with hot reload. See cli/README.md and the commands reference.

Extensions

Extensions are modules you compose into an app. Most are production ready; three are still being built.

Extension	What it does
auth	Multi-provider authentication (OAuth, JWT, SAML)
cache	Multi-backend caching (Redis, Memcached, in-memory)
consensus	Raft consensus for distributed systems
dashboard	Micro-frontend shell for admin dashboards
discovery	Service discovery and registry
events	Event bus and event sourcing
features	Feature flags and A/B testing
graphql	GraphQL server with schema generation
grpc	gRPC server with reflection
hls	HTTP Live Streaming
kafka	Apache Kafka integration
mcp	Model Context Protocol
mqtt	MQTT broker and client
security	Security hardening for production apps
streaming	WebSocket and SSE
webrtc	Peer-to-peer real-time communication
orpc	ORPC transport protocol (in progress)
queue	Message queue management (in progress)
search	Full-text search, Elasticsearch and Typesense (in progress)

The complete catalog covers configuration for each one.

Five extensions have been removed. What is left at ai, cron, database, gateway and storage is a migration note, not code. Use grove for databases, bastion for the API gateway, trove for object storage, dispatch for scheduled and background work, and cortex and its siblings for AI.

Composing an application

Extensions are declared in the app config. Services register against the container, and handlers resolve them from it:

app := forge.NewApp(forge.AppConfig{
    Name:        "my-service",
    Version:     "1.0.0",
    Environment: "production",

    Extensions: []forge.Extension{
        auth.NewExtension(auth.Config{
            Provider: "oauth2",
        }),
    },
})

db, err := grove.Open("postgres://localhost/mydb", grove.WithPoolSize(25))
if err != nil {
    return err
}

forge.RegisterSingleton(app.Container(), "userService", func(c forge.Container) (*UserService, error) {
    logger := forge.Must[forge.Logger](c, "logger")
    return NewUserService(db, logger), nil
})

router := app.Router()
router.GET("/users/:id", getUserHandler)
router.POST("/users", createUserHandler)

app.Run()

Switching a backend is a DSN change rather than a code change. Grove picks the driver from the scheme, so the same grove.Open call works whether it points at Postgres or SQLite.

Documentation

• Installation
• Quick start
• Architecture
• Application lifecycle
• Dependency injection
• Routing and middleware
• Configuration
• Observability

Full docs are at forge.dev. Questions and ideas go in Discussions; bugs go in Issues.

Examples

The examples directory has runnable services. Some worth starting with:

• di-patterns for container registration
• lifecycle-hooks for startup and shutdown ordering
• observability for metrics, logging and tracing
• simple-extension and runnable-extension for writing your own
• openapi-demo for generated API specs
• sse-streaming and webtransport for streaming transports
• auth and graphql for those extensions

Development

You need Go 1.24 or later. Make is optional but the targets below assume it.

make build          # build the CLI
make build-debug    # build with debug symbols
make release        # build for all platforms

make test           # all tests
make test-coverage  # with coverage
go test ./extensions/graphql/...

make fmt            # format
make lint           # lint
make lint-fix       # lint and fix
make security-scan  # security scan
make vuln-check     # check dependencies for known vulnerabilities
make ci             # everything CI runs

The dev server takes --watch for hot reload and --port to override the address:

forge dev --watch --port 3000

Contributing

Fork, branch, and open a pull request. Run make install-tools once, then make ci before you push.

Commits follow Conventional Commits, which the release tooling reads to decide the version bump. See CONTRIBUTING.md for the rest.

Releases

Releases run through Release Please and a GitHub Actions workflow.

Push to main with conventional commits and Release Please opens a PR carrying the version bumps and changelog. Merging that PR creates a tag, and the tag triggers the release pipeline. For a release you need to cut by hand, go to Actions > Release and run the workflow against a chosen module and version.

The pipeline builds cross-platform binaries and Docker images for the main module and CLI and publishes them to Homebrew, Scoop and NFPM through GoReleaser. Extension modules get a GitHub release and a notification to the Go module proxy. Dry-run mode validates the whole pipeline without publishing, and tests can be skipped for a hotfix that CI has already verified.

License

Apache License 2.0. See LICENSE.

Acknowledgments

Built by Rex Raphael, with thanks to Bun for the SQL ORM, Uptrace for observability, and Chi, whose router shaped the design of this one.