superapi

command module
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 4, 2026 License: Apache-2.0 Imports: 1 Imported by: 0

README

Go Version License Release

SuperAPI

Production-grade Go API template for SaaS backends.

IMPORTANT NOTICE

This is a TEMPLATE repository.

  • Do NOT install via go get
  • Use "Use this template" to create a new project
  • Generated projects are independent and do NOT auto-update

What This Is

SuperAPI is a modular Go API foundation focused on production use from day one.

It provides:

  • a module-oriented API architecture
  • policy-based middleware wiring
  • built-in auth, caching, rate limiting, and observability primitives

Start here:

Features

  • Module system for explicit, composable API domains
  • Strict startup validation for runtime and policy configuration
  • goAuth integration for route-level authentication workflows
  • Redis-backed response cache and Redis-backed rate limiting
  • Observability stack: metrics, tracing, and structured logs
  • sqlc + pgx workflow for typed query access
  • Built-in scaffolder for generating production-oriented modules

Quick Start

1. Click "Use this template"
2. Clone your new repo
3. go run ./cmd/api

After startup:

  • Liveness: GET /healthz
  • Readiness: GET /readyz
Minimal mode (no external dependencies)

Use the profile that disables Postgres, Redis, auth, cache, and rate limiting:

cp .env.example .env
# edit .env and enable:
# APP_PROFILE=minimal

go run ./cmd/api
Full mode (Postgres + Redis + auth)

Use .env.example full-mode defaults, then run:

go run ./cmd/api

Required full-mode toggles are already shown in .env.example:

  • POSTGRES_ENABLED=true + valid POSTGRES_URL
  • REDIS_ENABLED=true + valid REDIS_ADDR
  • AUTH_ENABLED=true
  • RATELIMIT_ENABLED=true
  • CACHE_ENABLED=true

How To Build APIs

  1. Create a module
make module name=projects

Expected output:

generated module "projects" (package="projects" route=/api/v1/projects)

This creates:

  • internal/modules/projects/module.go
  • internal/modules/projects/routes.go
  • internal/modules/projects/dto.go
  • internal/modules/projects/handler.go
  • internal/modules/projects/service.go
  • internal/modules/projects/repo.go
  • internal/modules/projects/handler_test.go
  • internal/modules/projects/service_test.go
  1. Confirm module wiring

internal/modules/modules.go is updated automatically with import + projects.New() entry.

  1. Verify and run
go test ./internal/devx/modulegen ./internal/modules/projects
go run ./cmd/superapi-verify ./internal/modules/projects
go run ./cmd/api

  1. Add handlers and service logic in the generated module files under internal/modules/projects/.

  2. Add routes in routes.go and attach policies as needed (auth, tenant, rate limit, cache).

Guides:

Docs Navigation

Philosophy

  • Secure by default in production-sensitive paths
  • Explicit policies over implicit behavior
  • Fail-fast validation at startup for unsafe configurations
  • No hidden magic or global side effects where avoidable

Versioning And Updates

  • This template is distributed as a snapshot.
  • Generated repositories do not receive automatic upstream updates.
  • Upgrades are manual: compare changes, port intentionally, and validate with tests/build.
  • Current public template baseline: v0.5.0 (pre-1.0 by intent).

Release Hygiene

Before publishing a downstream release:

go test ./...
go build ./...

Contributing

Contribution process and governance rules are documented in CONTRIBUTING.md.

Documentation

Overview

Package main provides the repository placeholder entrypoint.

Use cmd/api for the production server bootstrap.

Source Files

View all Source files

Directories

Path Synopsis
cmd
api command
Command api starts the SuperAPI HTTP server using environment-driven configuration.
 Command api starts the SuperAPI HTTP server using environment-driven configuration.
authgen command
Command authgen scaffolds goAuth bootstrap artifacts for SuperAPI projects.
 Command authgen scaffolds goAuth bootstrap artifacts for SuperAPI projects.
migrate command
Command migrate applies and manages database migrations for SuperAPI.
 Command migrate applies and manages database migrations for SuperAPI.
modulegen command
Command modulegen creates new module scaffolds with optional policy and DB wiring.
 Command modulegen creates new module scaffolds with optional policy and DB wiring.
modulesync command
Command modulesync syncs module-level schema/query files into shared sqlc directories.
 Command modulesync syncs module-level schema/query files into shared sqlc directories.
perftoken command
Command perftoken generates auth tokens for load and performance testing workflows.
 Command perftoken generates auth tokens for load and performance testing workflows.
superapi-verify command
Command superapi-verify runs static route and policy validation across the codebase.
 Command superapi-verify runs static route and policy validation across the codebase.
internal
core/app
Package app wires the HTTP server, module registration, and lifecycle management.
 Package app wires the HTTP server, module registration, and lifecycle management.
core/auth
Package auth provides authentication context types and goAuth provider integration.
 Package auth provides authentication context types and goAuth provider integration.
core/cache
Package cache implements Redis-backed response caching and cache key generation utilities.
 Package cache implements Redis-backed response caching and cache key generation utilities.
core/config
Package config loads, normalizes, and validates runtime configuration from environment variables.
 Package config loads, normalizes, and validates runtime configuration from environment variables.
core/db
Package db provides Postgres/sqlc integration, migrations, and transaction helpers.
 Package db provides Postgres/sqlc integration, migrations, and transaction helpers.
core/db/sqlcgen
core/errors
Package errors defines typed application errors used for consistent API responses.
 Package errors defines typed application errors used for consistent API responses.
core/httpx
Package httpx contains HTTP adapters, middleware, and router helpers used by modules.
 Package httpx contains HTTP adapters, middleware, and router helpers used by modules.
core/logx
Package logx wraps structured logging setup and logger configuration.
 Package logx wraps structured logging setup and logger configuration.
core/metrics
Package metrics provides Prometheus instrumentation for HTTP, readiness, and policy signals.
 Package metrics provides Prometheus instrumentation for HTTP, readiness, and policy signals.
core/modulekit
Package modulekit provides module-safe accessors for runtime dependencies.
 Package modulekit provides module-safe accessors for runtime dependencies.
core/netx
Package netx contains network helpers such as trusted client IP extraction.
 Package netx contains network helpers such as trusted client IP extraction.
core/params
Package params provides normalized request parameter helper functions.
 Package params provides normalized request parameter helper functions.
core/policy
Package policy provides route-level middleware for auth, RBAC, tenant checks, rate limiting, and cache control.
 Package policy provides route-level middleware for auth, RBAC, tenant checks, rate limiting, and cache control.
core/ratelimit
Package ratelimit implements Redis-backed rate limiting primitives and keying strategies.
 Package ratelimit implements Redis-backed rate limiting primitives and keying strategies.
core/readiness
Package readiness aggregates dependency health into a sanitized readiness report.
 Package readiness aggregates dependency health into a sanitized readiness report.
core/requestid
Package requestid defines request-id context storage and retrieval helpers.
 Package requestid defines request-id context storage and retrieval helpers.
core/response
Package response writes API envelopes and error payloads with centralized sanitization.
 Package response writes API envelopes and error payloads with centralized sanitization.
core/tenant
Package tenant provides tenant-scope utilities used by auth and policy layers.
 Package tenant provides tenant-scope utilities used by auth and policy layers.
core/tracing
Package tracing configures OpenTelemetry provider lifecycle for the API process.
 Package tracing configures OpenTelemetry provider lifecycle for the API process.
devx/modulegen
Package modulegen provides scaffolding utilities for creating new API modules.
 Package modulegen provides scaffolding utilities for creating new API modules.
devx/modulesync
Package modulesync syncs module-local SQL assets into global sqlc input folders.
 Package modulesync syncs module-local SQL assets into global sqlc input folders.
modules
Package modules registers built-in runtime modules for the API process.
 Package modules registers built-in runtime modules for the API process.
modules/health
Package health exposes liveness and readiness endpoints as an app module.
 Package health exposes liveness and readiness endpoints as an app module.
modules/system
Package system provides system-level example routes, auth demos, and utility endpoints.
 Package system provides system-level example routes, auth demos, and utility endpoints.
tools/validator
Package validator statically validates route policy wiring for SuperAPI modules.
 Package validator statically validates route policy wiring for SuperAPI modules.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.