Documentation
¶
Index ¶
- func ConnectDB(cfg Config) (*pgxpool.Pool, error)
- func Transaction(ctx context.Context, pool *pgxpool.Pool, fn TransactionFunc) error
- func TransactionWithJobs(ctx context.Context, pool *pgxpool.Pool, client *river.Client[pgx.Tx], ...) error
- type App
- func (a *App) Listen(addr string) error
- func (a *App) Pool() *pgxpool.Pool
- func (a *App) RegisterAPIRoutes(fn func(huma.API)) *App
- func (a *App) RegisterHTMLRoutes(fn func(chi.Router)) *App
- func (a *App) RegisterPublicRoutes(fn func(chi.Router)) *App
- func (a *App) RequireAuth() *App
- func (a *App) UseAPIKeyStore(ks auth.APIKeyStore) *App
- func (a *App) UseOAuth(cfg auth.OAuthConfig, findOrCreateUser auth.UserFinder) *App
- func (a *App) UsePasswordAuth(authenticateUser auth.PasswordAuthenticator) *App
- func (a *App) UsePool(pool *pgxpool.Pool) *App
- func (a *App) UseRecovery(mw func(http.Handler) http.Handler) *App
- func (a *App) UseTokenStore(ts auth.TokenStore) *App
- type Config
- type DB
- type Error
- func BadRequest(message string) *Error
- func Forbidden(message string) *Error
- func ForeignKeyViolation(field string) *Error
- func InternalError(err error) *Error
- func NewValidationError(errs interface{}) *Error
- func NotFound(resource string, id any) *Error
- func Unauthorized(message string) *Error
- func UniqueViolation(field string) *Error
- type TransactionFunc
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ConnectDB ¶
ConnectDB creates a pgxpool.Pool from the given Config. Call this early in main() so the pool is available for registry wiring.
func Transaction ¶
Transaction wraps pgx.BeginFunc to provide a clean transaction API. The transaction commits if fn returns nil, and rolls back if fn returns an error.
func TransactionWithJobs ¶
func TransactionWithJobs(ctx context.Context, pool *pgxpool.Pool, client *river.Client[pgx.Tx], fn func(ctx context.Context, tx pgx.Tx, jobs *river.Client[pgx.Tx]) error) error
TransactionWithJobs wraps a transaction and provides a River client for transactional job enqueueing. Jobs enqueued with client.InsertTx will only be visible after the transaction commits. The transaction commits if fn returns nil, and rolls back if fn returns an error.
Types ¶
type App ¶
type App struct {
// contains filtered or unexported fields
}
App is the forge application lifecycle manager. Create with New(), configure with builder methods, start with Listen().
func (*App) Listen ¶
Listen starts the HTTP server and blocks until SIGTERM/SIGINT. On shutdown: stops accepting connections, drains in-flight requests, closes the DB pool (if created internally).
func (*App) Pool ¶
Pool returns the database connection pool. Only valid after Listen() has been called (for test infrastructure, use forge/forgetest).
func (*App) RegisterAPIRoutes ¶
RegisterAPIRoutes sets the function that registers all API routes on the Huma API. The function receives a huma.API and should call genapi.RegisterAllRoutes(api, registry).
func (*App) RegisterHTMLRoutes ¶
RegisterHTMLRoutes sets the function that registers all HTML routes on a chi.Router. The function receives a session-protected chi.Router group.
func (*App) RegisterPublicRoutes ¶
RegisterPublicRoutes sets a function that registers routes outside the RequireSession middleware group. Use this for custom unauthenticated pages.
func (*App) RequireAuth ¶
RequireAuth enables session enforcement on HTML routes. Unauthenticated users are redirected to /auth/login.
func (*App) UseAPIKeyStore ¶
func (a *App) UseAPIKeyStore(ks auth.APIKeyStore) *App
UseAPIKeyStore sets the API key store for API authentication.
func (*App) UseOAuth ¶
func (a *App) UseOAuth(cfg auth.OAuthConfig, findOrCreateUser auth.UserFinder) *App
UseOAuth configures OAuth2 providers (Google/GitHub) for HTML session auth.
func (*App) UsePasswordAuth ¶
func (a *App) UsePasswordAuth(authenticateUser auth.PasswordAuthenticator) *App
UsePasswordAuth configures email/password authentication for HTML session auth.
func (*App) UsePool ¶
UsePool sets an externally-created database connection pool. When set, Listen() will skip internal pool creation and use this pool instead. The caller is responsible for closing the pool after Listen() returns.
func (*App) UseRecovery ¶
UseRecovery sets a custom panic recovery middleware. If not called, a default passthrough middleware is used.
func (*App) UseTokenStore ¶
func (a *App) UseTokenStore(ts auth.TokenStore) *App
UseTokenStore sets the bearer token store for API authentication.
type Config ¶
type Config struct {
// contains filtered or unexported fields
}
Config is the runtime configuration for a forge application. Load from forge.toml with LoadConfig, or construct programmatically for testing.
func LoadConfig ¶
LoadConfig reads forge.toml from the given path and returns a Config. Environment variable overrides (FORGE_*) are applied automatically.
func (Config) DatabaseURL ¶
DatabaseURL returns the configured database connection string.
func (Config) ServerAddr ¶
ServerAddr returns the configured host:port for the HTTP server.
type DB ¶
type DB interface {
Exec(ctx context.Context, sql string, arguments ...interface{}) (pgconn.CommandTag, error)
Query(ctx context.Context, sql string, args ...interface{}) (pgx.Rows, error)
QueryRow(ctx context.Context, sql string, args ...interface{}) pgx.Row
}
DB is an interface compatible with pgx transaction types. It allows code to accept either a pool or a transaction.
type Error ¶
type Error struct {
// Status is the HTTP status code (e.g. 400, 404, 500).
Status int
// Code is a machine-readable error code (e.g. "not_found", "validation_error").
Code string
// Message is a human-readable error summary.
Message string
// Detail provides additional context for debugging (may be empty).
Detail string
// Err is the underlying error, if any.
Err error
}
Error represents a structured application error with HTTP status code mapping. Both API (JSON) and HTML (SSE) handlers use this type for consistent error responses.
func BadRequest ¶
BadRequest returns a 400 error for invalid requests.
func ForeignKeyViolation ¶
ForeignKeyViolation returns a 400 error for foreign key constraint violations.
func InternalError ¶
InternalError returns a 500 error wrapping an unexpected error.
func NewValidationError ¶
func NewValidationError(errs interface{}) *Error
NewValidationError creates a 422 error from validation errors. Accepts any type with an Error() method to avoid importing validation package.
func Unauthorized ¶
Unauthorized returns a 401 error for authentication failures.
func UniqueViolation ¶
UniqueViolation returns a 409 error for unique constraint violations.
Source Files
Directories