toolbelt

The shared platform for applications built at git.animeteamspeak.moe/ginjiruu. Consumed by ginjiruu/go-template and every project scaffolded from it. Extends delaneyj/toolbelt (kept as a dependency) with embedded OpenFGA, a durable-projector framework, the event envelope, an SCS NATS-KV session store, the field-driven config framework, and the composition root used to wire features.

Packages

Package	Purpose
app	Composition root. Owns the shared-infrastructure lifecycle and exposes it to features via Component + the Feature interface.
config	Field-driven configuration framework (Viper-backed registry, Field structs, BuildLogger, validators).
oapi	Runtime binding for spec-driven JSON APIs: OpenAPI spec loader + kin-openapi request-validation middleware for chi + structured error mapping.
db	Embedded SQLite wrapper with fs.FS-backed migrations.
embeddednats	Embedded NATS setup (free port, store dir, logging).
embeddedfga	Embedded OpenFGA server, client, model bootstrapper, and tuple sources (YAML/file/mock).
embeddedoidc	Embedded standards-compliant OIDC provider (zitadel-backed) plus Login, an automated auth-code login flow for dev servers and tests.
events	Generic event envelope, DOMAIN stream config, publisher with optimistic concurrency.
projector	Durable pull-consumer that applies DOMAIN-log events to one store (idempotent applies).
sessions/natskv	SCS session store backed by a NATS JetStream KV bucket.
authn	Standard OIDC relying-party authentication feature: installs Component.Authed, mounts /login /callback /logout, exposes RequireAuth, UserFromContext, and the UserProvision identity seam.
cqrs	NATS KV projection writer used as the SSE read model.
server	chi router scaffolding: standard middleware, SSE-aware timeout, access logger.
coverage	FGA model test-coverage analysis (used by the fga-coverage tool).

Tools

Schema-codegen tools live in the nested tools/ module (own go.mod): fga-generate (emit Go type/relation constants from .fga models), fga-coverage, kcl-generate (emit the config Field registry and a typed Config struct from a KCL schema.k), and oapi-generate (emit types, a chi ServerInterface, and an embedded spec from an openapi.yaml via oapi-codegen). kcl-generate embeds the platform's universal schema (logging fields), so generated configs always include log.level / log.format.

The config/kcl package is the opt-in runtime binding: importing it registers a .k file loader and exposes kcl.ValidateConfig for enforcing schema check/rule blocks over the fully resolved config, plus kcl.SetField for config set on KCL files.

The oapi package is the runtime half of the spec-driven JSON API story: load an OpenAPI spec (oapi.Load from bytes, or oapi.LoadSpec from an oapi-codegen-generated GetSwagger() document), mount Validator.Middleware on the chi subrouter serving the API, and every request is validated against the spec. Rejected requests get a structured JSON error via oapi.WriteError (route/method/param/body failures mapped to 404/405/400/422/415). Pair it with the oapi-generate tool for the full OpenAPI → code + validation pipeline.

Using it

import "git.animeteamspeak.moe/ginjiruu/toolbelt/app"

a, err := app.New(ctx, logger, app.Config{...}, app.Options{
	ModelFS:      fgaModelFS,
	MigrationsFS: migrationsFS,
	Features:     []app.Feature{...},
})
defer a.Close()
return a.Run(ctx)

See ginjiruu/go-template for a full reference application.