servicekit

import "github.com/infobloxopen/devedge-sdk/servicekit"

Package servicekit is the runtime a scaffolded service runs on. It splits a service into an importable Module (the service’s domain wiring) and an executable host (HostConfig + Run) that builds one shared server.Server, registers the modules on it, and serves under the fail-closed boot gate. devedge-sdk new service generates a host in cmd/<svc>/main.go and a module in module/, both built on this package.

Use this reference when you change how a scaffolded service is hosted: adding a custom gRPC handler, hosting a second resource, registering a readiness check, or composing several modules into one binary. For the task recipe, see Add a custom method or second resource.

The package lives in the SDK’s root module and depends only on the SDK’s root interfaces (server.Server, persistence.Repository, events.Bus, health.Check, authz.MethodRule, and log/slog). Concrete backends (gorm, ent, otel, kafka) stay in the optional adapter sub-modules, so the core stays dependency-light.

Module and host

A service is two parts:

• A module owns domain behavior: its resources, handlers, repositories, migrations, events, config schema, health checks, and authz rules. A module is importable and self-describing.
• A host owns process behavior: listen addresses, flags, environment, the database connection, the logger, signal handling, and process exit. The host hands its modules to Run.

The same module runs two ways with no code change. A standalone host gives Run one module; a composed “suite” host gives Run several. See Composable services.

Module

type Module interface {
    Descriptor() Descriptor
    Register(ctx context.Context, app *App) error
}

Module is the unit of composition. A service that runs protoc-gen-svc gets a generated <Service>Module(<Service>ModuleOptions{...}) constructor that returns a Module. The generated module’s Descriptor is populated from proto facts, and its Register wires the generated CRUD handler onto the shared server.

A Register implementation must not start listeners, parse flags, call os.Exit, or otherwise take over the process.

Descriptor

type Descriptor struct {
    ID          string
    DisplayName string
    Version     string

    Methods    []string
    AuthzRules []authz.MethodRule
    Routes     []RouteDescriptor
    Resources  []ResourceDescriptor

    Config         ConfigDescriptor
    Database       DatabaseDescriptor
    Events         EventDescriptor
    HealthChecks   []HealthDescriptor
    BackgroundJobs []JobDescriptor

    Requires      Compatibility
    FailurePolicy FailurePolicy
}

Descriptor is a module’s static, introspectable facts — known before boot so the host can validate the composition and so tooling can describe a suite without running it. The generated <Service>Module populates the proto-derived fields (ID, Methods, AuthzRules, Resources); hand-written extras flow in through the module’s options.

Config, events, and database descriptors

These nested descriptors declare the seams the host wires per module:

type ConfigDescriptor struct {
    Prefix   string         // per-module config namespace (e.g. "orders")
    Schema   any            // pointer to the module's typed config struct
    Defaults map[string]any // programmatic defaults beneath the struct default: tags
}

type DatabaseDescriptor struct {
    Isolation   IsolationPolicy // namespacing policy; empty defers to the host default
    Schema      string          // preferred Postgres schema (defaults to the module ID)
    TablePrefix string          // table prefix for prefix-isolation engines
    Migrations  MigrationsFS    // the module's embedded migrations (satisfied by embed.FS)
}

type EventDescriptor struct {
    Publishes  []EventType     // globally-unique event type names the module emits
    Subscribes []EventType     // event type names the module consumes
    Outbox     OutboxDescriptor
}

MigrationsFS is an alias for the standard io/fs.FS, so an embed.FS satisfies it directly. The host reads Migrations and runs them per module under an advisory lock; a module never runs its own migrations from init. See Add a custom method or second resource.

App

type App struct {
    Server  *server.Server
    Config  ConfigProvider
    DB      DatabaseRegistry
    Events  EventRegistry
    Health  HealthRegistry
    Logger  *slog.Logger
    Metrics MetricsRegistry
}

App is the running host’s shared services, handed to each Module.Register. Each module receives its own App: its registry seams are scoped to that module’s ID, so config, database namespace, metrics, and the event and job helpers all attribute their work to the registering module.

App also carries per-module helpers the host uses to own dispatchers and jobs across a composition:

func (a *App) ModuleID() string
func (a *App) Bus() events.Bus
func (a *App) RegisterOutboxRelay(cfg OutboxRelayConfig) error
func (a *App) Subscribe(cfg ConsumerConfig, handlers ...EventHandler) error
func (a *App) RegisterBackgroundJob(name string, fn func(ctx context.Context) error) error

App.Server bridge

app.Server is the bridge between a module and the generated Register<Service> helpers. The generated code registers a gRPC service on a *server.Server, so a module’s Register passes app.Server to it:

func (m *ordersModule) Register(_ context.Context, app *servicekit.App) error {
    return orderv1.RegisterOrderServiceWithRepository(app.Server, m.repo)
}

For a custom handler, register the handler instead of the repository:

func (m *ordersModule) Register(_ context.Context, app *servicekit.App) error {
    return orderv1.RegisterOrderService(app.Server, m.handler)
}

Either call records the service’s methods, contributes its <Service>AuthzRules, registers the implementation on gRPC, and wires the HTTP gateway. The boot-time authz completeness gate runs later, at server.Serve. See codegen → protoc-gen-svc for the generated helpers and server → Server methods for the Serve gate.

HostConfig

type HostConfig struct {
    Modules []Module

    GRPCAddr string
    HTTPAddr string

    HTTPHandlers []server.HTTPHandler

    Authorizer    authz.Authorizer
    PrincipalFunc grpcauthz.PrincipalFunc
    Authenticator authn.Authenticator
    Logger        *slog.Logger

    ConfigSources []config.Source
    Context       context.Context

    Database *DatabaseConfig
    Migrate  MigrationRunner
    Bus      events.Bus

    FailurePolicies      map[string]FailurePolicy
    DefaultFailurePolicy FailurePolicy
}

HostConfig is the process-level configuration the host owns. The same shape drives a standalone binary (one module) and a composed suite (several modules).

DatabaseConfig

type DatabaseConfig struct {
    Engine           string          // e.g. "postgres"; empty means no shared DB
    DefaultIsolation IsolationPolicy // composition default for modules with Isolation unset
}

A standalone host leaves HostConfig.Database nil and runs its single module’s migration through Migrate. A composed suite host sets Engine so each module gets its own schema or table prefix from its DatabaseDescriptor. See Composable services.

MigrationRunner

type MigrationRunner func(ctx context.Context, ns DatabaseNamespace, d DatabaseDescriptor) error

Run calls the MigrationRunner once per module — after the module’s DatabaseNamespace is allocated and before the module registers — so the host, not the module, runs migrations. The runner must be idempotent. The scaffold’s cmd/<svc>/main.go supplies one backed by gormtx.MigrateModule (GORM); the ent scaffold migrates with client.Schema.Create in main instead.

Run

func Run(hc HostConfig) error

Run is the host entrypoint. It builds the one shared server, registers every module on it, and serves — the same path whether one module or several. It runs this sequence:

1. Resolve host defaults and the root context. The host owns signal handling; with Context nil, Run installs a context cancelled on SIGTERM or Interrupt.
2. Validate the composition: unique module IDs, no duplicate gRPC service names, no duplicate route prefixes, no duplicate permission names, and a coherent event graph (no orphan subscriber).
3. Resolve the shared backends once: the one server with its interceptor chain, the one event bus, the config store, the per-module database registry, and the supervisor.
4. For each module, in slice order: allocate its database namespace, run its migrations under a per-module advisory lock through Migrate, then call Register inside the module’s panic boundary.
5. Start exactly one outbox relay and one consumer per module, plus every supervised background job, each in its module’s bulkhead.
6. Call server.Serve. The server’s fail-closed completeness gate validates the combined surface of every module, then blocks until the context is cancelled.
7. On shutdown, close the shared bus and wait for the supervised goroutines.

Run returns the first fatal error, or nil on clean shutdown. When a FailHost module takes the host down, Run returns that module’s failure cause rather than nil.

A minimal standalone host:

func runHost(ctx context.Context, authorizer authz.Authorizer, grpcAddr, httpAddr, dsn string) error {
    repo, gormDB, err := newRepository(dsn) // open the DB, build the generated repository
    if err != nil {
        return err
    }
    sqlDB, err := gormDB.DB()
    if err != nil {
        return err
    }
    return servicekit.Run(servicekit.HostConfig{
        Modules:       []servicekit.Module{svcmodule.Module(repo, sqlDB)},
        GRPCAddr:      grpcAddr,
        HTTPAddr:      httpAddr,
        Migrate:       moduleMigrate(gormDB),
        Authorizer:    authorizer,
        PrincipalFunc: grpcauthz.DevPrincipalFunc(),
        Logger:        slog.Default(),
        Context:       ctx,
    })
}

Registry interfaces

The host hands each module its registry seams through App. They are backed by real per-module implementations.

type ConfigProvider interface {
    Load(dst any) error
}

type DatabaseRegistry interface {
    Namespace(moduleID string, db DatabaseDescriptor) (DatabaseNamespace, error)
}

type EventRegistry interface {
    RegisterOutbox(moduleID string, d OutboxDescriptor) error
}

type HealthRegistry interface {
    Register(name string, check health.Check) error
}

type MetricsRegistry interface {
    Namespace(moduleID string) string
}

DatabaseNamespace and IsolationPolicy are aliases of the persistence types of the same name — the single source of truth shared with the gormtx and entrepo adapters that honor them.

Failure policy

type FailurePolicy string

const (
    FailurePolicyUnset FailurePolicy = ""          // defer to the host default
    FailHost           FailurePolicy = "fail-host" // a core module: a failure fails the host fast
    Degraded           FailurePolicy = "degraded"  // an optional module: a failure isolates the module
)

Run runs every module’s Register, background jobs, and dispatchers inside an in-process bulkhead. The FailurePolicy decides what a module failure does to the host:

• FailHost — a core module. A panic, a background-job crash, or a dispatcher failure cancels the host context, so the host fails fast. This is the conservative default and the standalone-friendly posture.
• Degraded — an optional module. A failure is isolated to that module: the module marks itself unready (its /readyz entry fails) and the host stays up.

The effective policy for a module is its HostConfig.FailurePolicies override, then its Descriptor.FailurePolicy, then HostConfig.DefaultFailurePolicy, then FailHost.

Composable services

The same module composes into a multi-service binary with no code change. A standalone host gives Run one module; a suite host gives Run several, sharing one server, one process, one event bus, and one database. Each module namespaces its own database tables under the host’s shared engine, and the host runs each module’s migrations under its own advisory lock. The host owns one relay and one consumer per module outbox, so a composed binary never double-starts a dispatcher.

The scaffold’s cmd/<svc>/main.go is a standalone host. The de compose tooling builds a suite host from several modules.

See also

• Add a custom method or second resource — the task recipe built on this package.
• server — the shared server.Server Run builds.
• codegen → protoc-gen-svc — the generated Module, handler, and Register<Service> helpers.
• Events — the outbox, relay, and consumer pipeline modules publish over.