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)
- type Boundary
- type Bucket
- type Codec
- type Database
- 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]
- type Guard
- type Handle
- type HashAlgo
- type Hasher
- type Key
- type MaskType
- type Masker
- type 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
- type Store
Constants ¶
This section is empty.
Variables ¶
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.
Functions ¶
func Config ¶
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.
Types ¶
type Boundary ¶ added in v0.0.5
Boundary wraps a cereal Processor and auto-registers with the service registry.
type Bucket ¶
Bucket wraps grub.Bucket and registers with scio on creation. Embed this type in your store structs to add custom methods.
type Database ¶
Database wraps grub.Database and registers with scio on creation. Embed this type in your store structs to add custom query methods.
type EncryptAlgo ¶ added in v0.0.5
type EncryptAlgo = cereal.EncryptAlgo
EncryptAlgo is a re-export of cereal.EncryptAlgo.
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 ¶
NewDebugEvent creates an Event that emits at Debug level.
func NewErrorEvent ¶
NewErrorEvent creates an Event that emits at Error level.
func NewEvent ¶
NewEvent creates an Event with the given signal and severity level. The variant is derived automatically from T via sentinel.
func NewInfoEvent ¶
NewInfoEvent creates an Event that emits at Info level.
func NewWarnEvent ¶
NewWarnEvent creates an Event that emits at Warn level.
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) Run ¶
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) WithCodec ¶ added in v0.0.5
WithCodec sets the default codec for cereal processors and the rocco engine.
func (*Service) WithEncryptor ¶ added in v0.0.5
WithEncryptor registers an encryptor for the given algorithm.
func (*Service) WithHasher ¶ added in v0.0.5
WithHasher registers a hasher for the given algorithm.
type ServiceInfo ¶
type ServiceInfo = slush.ServiceInfo
ServiceInfo describes a registered service for enumeration.
Source Files