sum

README

sum

Wire once, run anywhere. An application framework that unifies HTTP, data, configuration, and services into a single lifecycle.

Compose and Run

// Register services by contract type
k := sum.Start()
sum.Register[UserService](k, &userImpl{})
sum.Register[OrderService](k, &orderImpl{})
sum.Freeze(k)

// Retrieve anywhere by type
userSvc := sum.MustUse[UserService](ctx)

Services, configuration, and data stores—all wired through one registry, resolved by type.

Install

go get github.com/zoobzio/sum

Requires Go 1.24 or later.

Quick Start

package main

import (
    "context"
    "log"

    "github.com/zoobzio/sum"
)

type Greeter interface {
    Greet(name string) string
}

type greeterImpl struct{}

func (g *greeterImpl) Greet(name string) string {
    return "Hello, " + name
}

func main() {
    // Initialize service and registry
    svc := sum.New(sum.ServiceConfig{Host: "localhost", Port: 8080})
    k := sum.Start()

    // Register services
    sum.Register[Greeter](k, &greeterImpl{})
    sum.Freeze(k)

    // Use services anywhere
    greeter := sum.MustUse[Greeter](context.Background())
    log.Println(greeter.Greet("World"))

    // Run with graceful shutdown
    if err := svc.Run(); err != nil {
        log.Fatal(err)
    }
}

Capabilities

Capability	Description	Documentation
Service Registry	Type-safe service locator with guards	Registry
Lifecycle Management	Singleton service with graceful shutdown	Service
Configuration	Load and register config via fig	Config
Typed Events	Emit and listen with type-safe payloads	Event
Data Stores	Database, KV, and object storage helpers	Database

Why sum?

• Type-safe service registry — Register and retrieve services by contract type, not strings. Compile-time safety, zero casting.
• Unified lifecycle — One Run() handles startup, signal handling, and graceful shutdown.
• Integrated data catalog — Databases, KV stores, and buckets register automatically with the data catalog for observability.
• Typed events — Define events once with Event[T], emit and listen with full type safety.
• Minimal ceremony — No annotations, no reflection magic, no code generation. Just Go.

The Ecosystem

sum builds on the zoobzio toolkit:

Package	Purpose
rocco	HTTP engine with OpenAPI
slush	Service registry core
capitan	Event/signal system
fig	Configuration loading
grub	Database/KV/Object storage
scio	Data catalog

Documentation

• Learn: Overview · Quickstart · Concepts · Architecture
• Guides: Testing · Troubleshooting · Service Registry · Events · Data Stores
• Reference: API · Types · pkg.go.dev

Contributing

Contributions welcome—see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE

Documentation

Overview

Package sum provides an applications framework for Go.

Index

• Variables
• func Config[T any](ctx context.Context, k Key, provider fig.SecretProvider) error
• func Freeze(k Key)
• func MustUse[T any](ctx context.Context) T
• func Use[T any](ctx context.Context) (T, error)
• func WithToken(ctx context.Context, t Token) context.Context
• type Boundary
  • func NewBoundary[T cereal.Cloner[T]](k Key) (*Boundary[T], error)
• type Bucket
  • func NewBucket[M any](provider grub.BucketProvider, name string) (*Bucket[M], error)
• type Codec
• type Database
  • func NewDatabase[M any](db *sqlx.DB, table string, renderer astql.Renderer) (*Database[M], error)
• type EncryptAlgo
• type Encryptor
• type Event
  • func NewDebugEvent[T any](signal capitan.Signal) Event[T]
  • func NewErrorEvent[T any](signal capitan.Signal) Event[T]
  • func NewEvent[T any](signal capitan.Signal, level capitan.Severity) Event[T]
  • func NewInfoEvent[T any](signal capitan.Signal) Event[T]
  • func NewWarnEvent[T any](signal capitan.Signal) Event[T]
  • func (e Event[T]) Emit(ctx context.Context, data T)
  • func (e Event[T]) Listen(callback func(context.Context, T)) *capitan.Listener
  • func (e Event[T]) ListenOnce(callback func(context.Context, T)) *capitan.Listener
• type Guard
  • func Require(tokens ...Token) Guard
• type Handle
  • func Register[T any](k Key, impl T) *Handle[T]
  • func (h *Handle[T]) For(tokens ...Token) *Handle[T]
  • func (h *Handle[T]) Guard(g Guard) *Handle[T]
• type HashAlgo
• type Hasher
• type Key
  • func Start() Key
• type MaskType
• type Masker
• type Search
  • func NewSearch[M any](provider grub.SearchProvider, index string) (*Search[M], error)
• type Service
  • func New() *Service
  • func (s *Service) Catalog() *scio.Scio
  • func (s *Service) Engine() *rocco.Engine
  • func (s *Service) Handle(endpoints ...rocco.Endpoint)
  • func (s *Service) Run(host string, port int) error
  • func (s *Service) Shutdown(ctx context.Context) error
  • func (s *Service) Start(host string, port int) error
  • func (s *Service) Tag(name, description string)
  • func (s *Service) WithCodec(codec cereal.Codec) *Service
  • func (s *Service) WithEncryptor(algo cereal.EncryptAlgo, enc cereal.Encryptor) *Service
  • func (s *Service) WithHasher(algo cereal.HashAlgo, h cereal.Hasher) *Service
  • func (s *Service) WithMasker(mt cereal.MaskType, m cereal.Masker) *Service
• type ServiceInfo
  • func Services(k Key) ([]ServiceInfo, error)
• type Severity
• type Signal
• type Store
  • func NewStore[M any](provider grub.StoreProvider, name string) (*Store[M], error)
• type Token
  • func NewToken(name string) Token
  • func (t Token) String() string

Variables

var (
	Emit  = capitan.Emit
	Debug = capitan.Debug
	Info  = capitan.Info
	Warn  = capitan.Warn
	Error = capitan.Error
)

Emission function re-exports.

var (
	NewStringKey   = capitan.NewStringKey
	NewIntKey      = capitan.NewIntKey
	NewInt64Key    = capitan.NewInt64Key
	NewFloat64Key  = capitan.NewFloat64Key
	NewBoolKey     = capitan.NewBoolKey
	NewTimeKey     = capitan.NewTimeKey
	NewDurationKey = capitan.NewDurationKey
	NewErrorKey    = capitan.NewErrorKey
)

Field key constructor re-exports.

var (
	ErrNotFound     = slush.ErrNotFound
	ErrAccessDenied = slush.ErrAccessDenied
	ErrInvalidKey   = slush.ErrInvalidKey
)

Error re-exports from slush.

var (
	SignalRegistered capitan.Signal = slush.SignalRegistered
	SignalAccessed   capitan.Signal = slush.SignalAccessed
	SignalDenied     capitan.Signal = slush.SignalDenied
	SignalNotFound   capitan.Signal = slush.SignalNotFound
)

Signal re-exports from slush.

var (
	KeyInterface capitan.Key = slush.KeyInterface
	KeyImpl      capitan.Key = slush.KeyImpl
	KeyError     capitan.Key = slush.KeyError
)

Field key re-exports from slush.

var ErrTokenRequired = fmt.Errorf("token required")

ErrTokenRequired indicates a service requires a token but none was provided.

var NewSignal = capitan.NewSignal

NewSignal creates a signal with name and description.

Functions

func Config

func Config[T any](ctx context.Context, k Key, provider fig.SecretProvider) error

Config loads configuration of type T via fig and registers it with the service locator. Pass nil for provider if secrets are not needed. Retrieve the configuration later with Use[T](ctx).

func Freeze

func Freeze(k Key)

Freeze prevents further service registration. Panics if key is invalid.

func MustUse

func MustUse[T any](ctx context.Context) T

MustUse retrieves a service by its contract type T. Panics if the service is not registered or a guard fails.

func Use

func Use[T any](ctx context.Context) (T, error)

Use retrieves a service by its contract type T. Runs all registered guards with the provided context. Returns ErrNotFound if not registered, ErrAccessDenied if a guard fails.

func WithToken

func WithToken(ctx context.Context, t Token) context.Context

WithToken injects a token into the context.

Types

type Boundary

type Boundary[T cereal.Cloner[T]] struct {
	*cereal.Processor[T]
}

Boundary wraps a cereal Processor and auto-registers with the service registry.

func NewBoundary

func NewBoundary[T cereal.Cloner[T]](k Key) (*Boundary[T], error)

NewBoundary creates a Boundary[T], applies shared capabilities from the Service, and registers it in the service registry under the given key.

type Bucket

type Bucket[M any] struct {
	*grub.Bucket[M]
}

Bucket wraps grub.Bucket and registers with scio on creation. Embed this type in your store structs to add custom methods.

func NewBucket

func NewBucket[M any](provider grub.BucketProvider, name string) (*Bucket[M], error)

NewBucket creates a Bucket[M] and registers it with the scio catalog. Requires sum.New() to have been called first.

type Codec

type Codec = cereal.Codec

Codec is a re-export of cereal.Codec.

type Database

type Database[M any] struct {
	*grub.Database[M]
}

Database wraps grub.Database and registers with scio on creation. Embed this type in your store structs to add custom query methods.

func NewDatabase

func NewDatabase[M any](db *sqlx.DB, table string, renderer astql.Renderer) (*Database[M], error)

NewDatabase creates a Database[M] and registers it with the scio catalog. Requires sum.New() to have been called first.

type EncryptAlgo

type EncryptAlgo = cereal.EncryptAlgo

EncryptAlgo is a re-export of cereal.EncryptAlgo.

type Encryptor

type Encryptor = cereal.Encryptor

Encryptor is a re-export of cereal.Encryptor.

type Event

type Event[T any] struct {
	// Signal is the underlying capitan signal.
	Signal capitan.Signal

	// Key is the typed key for extracting event data.
	Key capitan.GenericKey[T]
	// contains filtered or unexported fields
}

Event provides bidirectional access to a signal with typed data. Use Emit to dispatch events and Listen to register callbacks.

func NewDebugEvent

func NewDebugEvent[T any](signal capitan.Signal) Event[T]

NewDebugEvent creates an Event that emits at Debug level.

func NewErrorEvent

func NewErrorEvent[T any](signal capitan.Signal) Event[T]

NewErrorEvent creates an Event that emits at Error level.

func NewEvent

func NewEvent[T any](signal capitan.Signal, level capitan.Severity) Event[T]

NewEvent creates an Event with the given signal and severity level. The variant is derived automatically from T via sentinel.

func NewInfoEvent

func NewInfoEvent[T any](signal capitan.Signal) Event[T]

NewInfoEvent creates an Event that emits at Info level.

func NewWarnEvent

func NewWarnEvent[T any](signal capitan.Signal) Event[T]

NewWarnEvent creates an Event that emits at Warn level.

func (Event[T]) Emit

func (e Event[T]) Emit(ctx context.Context, data T)

Emit dispatches an event with the configured severity level.

func (Event[T]) Listen

func (e Event[T]) Listen(callback func(context.Context, T)) *capitan.Listener

Listen registers a callback for this event. Returns a Listener that can be closed to unregister.

func (Event[T]) ListenOnce

func (e Event[T]) ListenOnce(callback func(context.Context, T)) *capitan.Listener

ListenOnce registers a callback that fires only once, then automatically unregisters. Returns a Listener that can be closed early to prevent the callback from firing.

type Guard

type Guard = slush.Guard

Guard is a validation function that permits or denies service access.

func Require

func Require(tokens ...Token) Guard

Require returns a guard that checks for any of the provided tokens. If the service has Require, the context must contain a matching token.

type Handle

type Handle[T any] struct {
	*slush.Handle[T]
}

Handle configures a registered service with optional guards. Wraps slush.Handle to provide sum-specific conveniences.

func Register

func Register[T any](k Key, impl T) *Handle[T]

Register registers a service implementation for the contract type T. Returns a Handle for optional guard configuration. Panics if Start has not been called, key is invalid, or registry is frozen.

func (*Handle[T]) For

func (h *Handle[T]) For(tokens ...Token) *Handle[T]

For restricts service access to contexts bearing any of the provided tokens. Equivalent to Guard(Require(tokens...)).

func (*Handle[T]) Guard

func (h *Handle[T]) Guard(g Guard) *Handle[T]

Guard adds a custom guard function to the service. Returns the Handle for chaining.

type HashAlgo

type HashAlgo = cereal.HashAlgo

HashAlgo is a re-export of cereal.HashAlgo.

type Hasher

type Hasher = cereal.Hasher

Hasher is a re-export of cereal.Hasher.

type Key

type Key = slush.Key

Key grants the capability to register services.

func Start

func Start() Key

Start initializes the service registry and returns a Key for registration. Panics if called more than once.

type MaskType

type MaskType = cereal.MaskType

MaskType is a re-export of cereal.MaskType.

type Masker

type Masker = cereal.Masker

Masker is a re-export of cereal.Masker.

type Search

type Search[M any] struct {
	*grub.Search[M]
}

Search wraps grub.Search and registers with scio on creation. Embed this type in your store structs to add custom query methods.

func NewSearch

func NewSearch[M any](provider grub.SearchProvider, index string) (*Search[M], error)

NewSearch creates a Search[M] and registers it with the scio catalog. Requires sum.New() to have been called first.

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service wraps a rocco engine and scio catalog, providing application lifecycle.

func New

func New() *Service

New creates or returns the singleton Service. Subsequent calls return the existing instance.

func (*Service) Catalog

func (s *Service) Catalog() *scio.Scio

Catalog returns the scio data catalog for advanced usage.

func (*Service) Engine

func (s *Service) Engine() *rocco.Engine

Engine returns the underlying rocco engine for advanced usage.

func (*Service) Handle

func (s *Service) Handle(endpoints ...rocco.Endpoint)

Handle registers endpoints with the underlying engine.

func (*Service) Run

func (s *Service) Run(host string, port int) error

Run starts the service and blocks until a shutdown signal is received. Handles SIGINT and SIGTERM, then performs graceful shutdown with a 30 second timeout.

func (*Service) Shutdown

func (s *Service) Shutdown(ctx context.Context) error

Shutdown gracefully stops the service.

func (*Service) Start

func (s *Service) Start(host string, port int) error

Start begins serving. This method blocks until shutdown.

func (*Service) Tag

func (s *Service) Tag(name, description string)

Tag registers an OpenAPI tag with a description.

func (*Service) WithCodec

func (s *Service) WithCodec(codec cereal.Codec) *Service

WithCodec sets the default codec for cereal processors and the rocco engine.

func (*Service) WithEncryptor

func (s *Service) WithEncryptor(algo cereal.EncryptAlgo, enc cereal.Encryptor) *Service

WithEncryptor registers an encryptor for the given algorithm.

func (*Service) WithHasher

func (s *Service) WithHasher(algo cereal.HashAlgo, h cereal.Hasher) *Service

WithHasher registers a hasher for the given algorithm.

func (*Service) WithMasker

func (s *Service) WithMasker(mt cereal.MaskType, m cereal.Masker) *Service

WithMasker registers a masker for the given mask type.

type ServiceInfo

type ServiceInfo = slush.ServiceInfo

ServiceInfo describes a registered service for enumeration.

func Services

func Services(k Key) ([]ServiceInfo, error)

Services returns information about all registered services. Returns ErrInvalidKey if the key is invalid.

type Severity

type Severity = capitan.Severity

Severity is the importance level of an emission.

type Signal

type Signal = capitan.Signal

Signal is a named event identifier.

type Store

type Store[M any] struct {
	*grub.Store[M]
}

Store wraps grub.Store and registers with scio on creation. Embed this type in your store structs to add custom methods.

func NewStore

func NewStore[M any](provider grub.StoreProvider, name string) (*Store[M], error)

NewStore creates a Store[M] and registers it with the scio catalog. Requires sum.New() to have been called first.

type Token

type Token struct {
	// contains filtered or unexported fields
}

Token is an unforgeable capability for service access.

func NewToken

func NewToken(name string) Token

NewToken creates a new access token with the given name.

func (Token) String

func (t Token) String() string

String returns the token name for debugging.