Application API reference

These decisions began as the phase 0 contract and now describe the implemented application API. Historical results remain in the phase reports.

Module and toolchain

The Go module is github.com/amkargar/gonex; the product name is goNex. The repository baseline is Go 1.27.2. Exact dependency versions are pinned in go.mod. See release policy for configured and verified platforms.

Construction and registration

• gonex.New(config.Config) (*app.App, error) validates settings without binding ports.
• Module.Register(*Registrar) error declares a module's routes and resources.
• App.Register(...Module) error registers explicitly in argument order, atomically per call.
• Registration freezes at startup. A failed registration call leaves the application unchanged.
• Registrar.Handle(method, path string, handlers ...gin.HandlerFunc) error is a raw Gin escape hatch. Use typed HTTP registration for public contracts.

Routing and contracts

Route identity is the uppercase method plus full path. Duplicate and incompatible wildcard routes fail before serving. Runtime health/readiness and enabled document paths reject conflicting registrations.

http.Routes groups concise typed declarations such as http.Get(path, handler).Name(operationID). Handler request and response types are inferred. The lower-level http.Register API remains available and builds the same typed endpoint contract. Request origins, supported validation constraints and schema projection are checked together. Contracts detach mutable metadata at registration. Raw Gin routes are not included in OpenAPI.

HTTP versions are explicit adapter packages. gRPC remains optional, with versioned Protobuf packages and independently managed servers/clients. See HTTP contracts and gRPC.

Resource ownership

Registrar.Manage(Resource) error owns resources implementing Start(context.Context) error and Close(context.Context) error. Registration order determines startup order; close runs in reverse. Dependencies register before their consumers. An optional Errors channel reports asynchronous failure to App.Run.

Registrar.Check(name, func(context.Context) error) adds a named dependency readiness check. Resources may also implement Ready(context.Context) error. Application callbacks must honor context cancellation.

Lifecycle guarantees

States are created, registered, starting, running, stopping and stopped. A stopped instance cannot restart. Configuration includes address, middleware, exposure switches and read/write/idle/shutdown timeouts. Zero durations use defaults; negative values fail. See modules and operations.