core

package module
v2.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 13, 2026 License: MIT Imports: 78 Imported by: 21

README

mine-core v2

A Go backend framework — v2. A clean-break rewrite over Echo, GORM, go-redis, resty, koanf, slog, and friends. Module path: github.com/pskclub/mine-core/v2 (Go 1.27).

v2 keeps v1's familiar interface names (IContext, IError, IENV, ICache, IMongoDB, IRequester, IMQ, ILogger, IModel, IRepository) but fixes v1's structural issues: context flows everywhere, no global state, no panics in the error path, and one library per job.

Quick start

env, _ := core.NewEnv()
db, _ := core.NewDatabase(env)
redis, _ := core.NewCache(env)

app, _ := core.NewApp(env,
    core.WithSQL("default", db),
    core.WithCache("default", redis),
)
defer app.Shutdown(context.Background())

e := core.NewHTTPServer(app, &core.HTTPOptions{AllowOrigins: []string{"*"}})
e.POST("/users", controller.CreateUser)
core.StartHTTPServer(e, env)

See docs/getting-started.md for a full example.

Documentation

Start here

Core

  • Context & App — IContext, App, ambient context, scoped data
  • Configuration (ENV) — koanf, URI/discrete connections
  • Error handling — IError, errmsgs, Recover
  • Logger — ILogger (slog)
  • Runner — start HTTP, jobs and consumers together, stop them in order
  • Health & readiness — /healthz and /readyz over the App's own dependencies
  • Sentry — automatic error tracking, breadcrumbs, logs, metrics, cron monitors, tracing

HTTP & validation

  • HTTP layer — server, routing, binding (path/query/form/json), groups
  • Authentication — JWT bearer middleware, roles, c.GetUser()
  • Validation — fluent rules, conditional/cross-field, reusable nested
  • Postman collection & OpenAPI — go tool postmangen generates both from the routes you already wrote
  • API reference — mount the generated OpenAPI as a Scalar page the team can send requests from

Data

Messaging & jobs

  • Pub/Sub — redis fan-out, subscribers with handlers
  • Message Queue — RabbitMQ publisher, topology and consumers
  • Scheduler — cron jobs (gocron v2)

Clients & integrations

Module status

Capability API Status
Errors core.IError / core.Error / errmsgs ✅ tested
Config core.IENV / core.ENVConfig (koanf) ✅ tested
Logger core.ILogger (slog) ✅ tested
Context / App core.IContext / core.App ✅ tested
Sentry core.ISentry (sentry-go) ✅ tested (recording transport)
Cache core.ICache (redis / in-memory) ✅ tested (memory backend); --tags=integration for redis
Pub/Sub core.IPubSub / core.ISubscriber ✅ tested (memory backend); --tags=integration for redis
SQL core.NewDatabase (gorm: postgres, mysql, sqlserver, oracle) ✅ tested (sqlite, DSN building)
Repository repository.Repo[M] ✅ tested (sqlite)
Validation valid.Validator ✅ tested
Requester core.IRequester (resty) ✅ compiled
HTTP core.IHTTPContext / NewHTTPServer (echo v5) ✅ tested (httptest)
Scheduler core.Scheduler (gocron v2) ✅ tested
JWT core.JWTSign / core.JWTVerify (golang-jwt v5) ✅ tested
CSV core.CSVMarshal / core.CSVUnmarshal ✅ tested
Mongo core.IMongoDB (mongo-driver) ✅ tested (URI, sorting, ids, paging); --tags=integration for mongo
Mongo repository mongorepo.Repo[D] / mongorepo.Aggregate[T] ✅ tested (query building); --tags=integration for mongo
MQ core.IMQ / core.IMQConsumer (amqp091) ✅ tested (pool, reconnect, topology, ack policy); integration needs rabbitmq
Storage core.IStorage (aws-sdk-go-v2 s3 / in-memory) ✅ tested (memory backend); --tags=integration for s3/minio
Mailer core.IMailer (go-mail) ✅ tested (memory backend, templates); integration needs smtp
Push core.IPusher (firebase v4) ✅ tested (memory backend, payload building); integration needs fcm
AI / LLM core.ILLM / llm/goai (zendev-sh/goai) ✅ tested (memory backend + conformance suite over a fake provider)
AI typed output llm.New[T](ctx) / llm.SchemaOf[T]() ✅ tested (schema reflection, parsing, validation)
AI attachments core.LLMImage / LLMFile on a message ✅ tested (validation, wire mapping; live vision against a real provider)
AI tool use core.LLMTool / llm.Tool[In] + Approve gate ✅ tested (loop, approval, panic guard; live against a real provider)
AI provider tools goai.GoogleSearch() / URLContext() / CodeExecution() → LLMResponse.Sources ✅ tested (wire mapping, grounding citations)
Embeddings core.IEmbedder.EmbedWith / llm/goai.NewEmbedder ✅ tested (memory backend, cosine similarity, per-provider Dimensions/Task mapping)
Health probes core.LiveHandler / core.ReadyHandler ✅ tested
Runner core.Runner ✅ tested (start/stop ordering)
Postman & OpenAPI generator cmd/postmangen (go tool postmangen) ✅ tested (golden collection and golden OpenAPI document over one fixture repo)
API reference apidocs.Mount(srv, apidocs.Options{…}) ✅ tested (guard, spec loading, servers, rendered page)

Contributing

Setup, build tags, the conventions a reviewer will push back on, and the release flow: CONTRIBUTING.md.

Testing

Tests use stretchr/testify as the standard: require for preconditions (stops the test) and assert for value checks. Prefer require.NoError / assert.Equal / assert.ErrorIs over hand-written if ... t.Fatalf.

import (
    "github.com/stretchr/testify/assert"
    "github.com/stretchr/testify/require"
)

func TestThing(t *testing.T) {
    got, err := DoThing()
    require.NoError(t, err)
    assert.Equal(t, want, got)
}
go test ./...            # unit tests (no external services)
go test -race ./...      # race detector (clean — no global state)

Consuming services build their fixtures with coretest — a context on a real database, an HTTP client that speaks the framework's error shape, and a job runner, so none of that wiring is rewritten per repository.

Documentation

Overview

Package core is the root of mine-core v2. It holds the request/job context (IContext), the application container (App), and the structured error type (IError/Error) that flows through every layer of the framework.

Index

Constants

View Source
const (
	// KeepTTL as the ttl of Set keeps whatever expiry the key already had.
	KeepTTL = redis.KeepTTL
	// NoExpiry as the ttl of Set stores the value until it is deleted. It is
	// also what TTL reports for a key that never expires.
	NoExpiry = time.Duration(0)
	// TTLNoExpiry is what TTL returns for a key that exists but has no expiry.
	TTLNoExpiry = time.Duration(-1)
)
View Source
const (
	DriverPostgres  = "postgres"
	DriverMySQL     = "mysql"
	DriverSQLServer = "sqlserver"
	DriverOracle    = "oracle"
)

SQL driver identifiers.

View Source
const (
	// HealthUp means every critical dependency answered.
	HealthUp = "up"
	// HealthDegraded means a non-critical dependency is down. The probe still
	// answers 200: the service can serve, just not everything.
	HealthDegraded = "degraded"
	// HealthDown means a critical dependency is down. The probe answers 503 and
	// the orchestrator takes the instance out of rotation.
	HealthDown = "down"
)

Health states, as reported in the probe body.

View Source
const (
	SourcePath   = "path"
	SourceQuery  = "query"
	SourceHeader = "header"
	SourceBody   = "body"
)

Where a bound value came from. The names match OpenAPI's `in`, so a client generator or an API console can use them directly.

View Source
const (
	DefaultQueue        = "default"
	DefaultJobTimeout   = 5 * time.Minute
	DefaultStopGrace    = 30 * time.Second
	DefaultRetainRuns   = 30 * 24 * time.Hour
	DefaultRetainLogs   = 7 * 24 * time.Hour
	DefaultLogMaxLines  = 1000
	DefaultLogMaxBytes  = 256 << 10
	DefaultLogTailLines = 50
	// DefaultSlotBackoff is how long a run waits before retrying to get a
	// concurrency slot under ConcurrencyEnqueue.
	DefaultSlotBackoff = 2 * time.Second
)

Job runner defaults.

View Source
const (
	// DefaultLimiterLease is how long a slot stays held without a heartbeat.
	// It is the window in which a replica that died mid-run still counts against
	// the limit: long enough that an ordinary network hiccup does not hand the
	// slot away, short enough that a crash does not wedge a singleton job.
	DefaultLimiterLease = 30 * time.Second
	// DefaultLimiterPrefix namespaces the limiter's keys under the cache's own
	// prefix.
	DefaultLimiterPrefix = "limiter:"
)

Redis limiter defaults.

View Source
const (
	ExchangeDirect  = "direct"
	ExchangeFanout  = "fanout"
	ExchangeTopic   = "topic"
	ExchangeHeaders = "headers"
)

Exchange kinds.

View Source
const (
	// DefaultMQPrefetch is how many unacknowledged messages the broker will
	// hand this consumer. It is the backpressure knob: too low and the consumer
	// waits on the network between messages, too high and one instance takes
	// work it cannot get to while another sits idle.
	DefaultMQPrefetch = 10
	// DefaultMQHandlerTimeout bounds one handler.
	DefaultMQHandlerTimeout = 30 * time.Second
	// DefaultMQReconnectDelay is how long a consumer waits before redialling a
	// broker that went away.
	DefaultMQReconnectDelay = 2 * time.Second
)

DefaultMQ consumer settings.

View Source
const (
	// DefaultMQPublishTimeout bounds one publish, waiting for the broker's
	// confirmation included. A request context with a shorter deadline still
	// wins — this is the ceiling, not the deadline.
	DefaultMQPublishTimeout = 5 * time.Second
	// DefaultMQChannels is how many publishes may be in flight at once. An AMQP
	// channel may only be used by one goroutine at a time, so this is both the
	// size of the channel pool and the concurrency limit.
	DefaultMQChannels = 8
)

MQ publisher defaults.

View Source
const (
	PageLimitDefault int64 = 30
	PageLimitMax     int64 = 10000
)

Pagination defaults. Both match v1 (consts.PageLimitDefault, consts.PageLimitMax), so a service moving to v2 keeps the page sizes its clients already see.

PageLimitMax is deliberately high: some endpoints are data APIs whose callers pull a working set in one request rather than page through it, and clamping those returns a short page with no error and nothing in the logs — the caller silently gets less than it asked for. The cap still bounds the worst case, but it is not a hint about response size. An endpoint that wants a tighter ceiling clamps PageOptions.Limit itself.

View Source
const (
	LevelDebug   = sentry.LevelDebug
	LevelInfo    = sentry.LevelInfo
	LevelWarning = sentry.LevelWarning
	LevelError   = sentry.LevelError
	LevelFatal   = sentry.LevelFatal
)
View Source
const (
	CheckInProgress = sentry.CheckInStatusInProgress
	CheckInOK       = sentry.CheckInStatusOK
	CheckInError    = sentry.CheckInStatusError
)
View Source
const (
	UnitMillisecond = sentry.UnitMillisecond
	UnitSecond      = sentry.UnitSecond
	UnitByte        = sentry.UnitByte
	UnitKilobyte    = sentry.UnitKilobyte
	UnitMegabyte    = sentry.UnitMegabyte
	UnitPercent     = sentry.UnitPercent
	UnitRatio       = sentry.UnitRatio
)

Units a metric can be recorded in. These are the ones a backend actually reaches for; any string sentry-go accepts works too.

View Source
const DefaultBodyLimit int64 = 10 << 20

DefaultBodyLimit is how large a request body may be before it is rejected with 413 REQUEST_TOO_LARGE.

Without a limit the body is read into memory by whatever binds it, so the largest request anybody sends is the memory footprint of the process — one client can end the service for everyone. Ten megabytes is far above any JSON payload; routes that take uploads set their own (see BodyLimit).

View Source
const DefaultCSVTimeLayout = time.RFC3339

DefaultCSVTimeLayout is how time values are written and read.

View Source
const DefaultGracefulTimeout = 10 * time.Second

DefaultGracefulTimeout bounds how long in-flight requests have to finish once a shutdown signal arrives.

View Source
const DefaultHealthTimeout = 3 * time.Second

DefaultHealthTimeout bounds the whole readiness probe. It is short on purpose: a probe that hangs is a probe that gets killed, and an instance whose database takes ten seconds to answer is not ready however the check eventually ends.

View Source
const DefaultIdleTimeout = 120 * time.Second

DefaultIdleTimeout is how long an idle keep-alive connection is kept.

Without it a connection that has finished its request stays open until the client drops it, and a load balancer that opens connections faster than it closes them slowly exhausts the file descriptors of the process.

View Source
const DefaultMailTimeout = 30 * time.Second

DefaultMailTimeout bounds one delivery, connection included.

View Source
const DefaultPushTimeout = 15 * time.Second

DefaultPushTimeout bounds one send.

View Source
const DefaultReadHeaderTimeout = 20 * time.Second

DefaultReadHeaderTimeout is how long a client has to send its request line and headers.

This is the deadline that closes the slow-loris hole properly. ReadTimeout has to be generous because a legitimate upload takes minutes; headers never do, so a connection that has not finished them in twenty seconds is not a client with a poor connection, it is a connection held open to occupy a worker.

View Source
const DefaultReadTimeout = 5 * time.Minute

DefaultReadTimeout is how long a client has to send its request, headers and body included.

echo v5 sets 30 seconds, which is a fine number for a JSON API and a wrong one for the rest of what services do: a file upload on a phone connection, a long-poll, an SSE stream. Those would be cut off mid-request with no error worth reading. Five minutes still closes the slow-loris hole echo's default exists for, while leaving normal work alone.

Override it per server with your own BeforeServeFunc — it runs after this one, so it wins:

e.Serve(ctx, echo.StartConfig{
    Address: ":8080",
    BeforeServeFunc: func(srv *http.Server) error {
        srv.ReadTimeout = 30 * time.Second
        return nil
    },
})
View Source
const LLMMaxAttachmentBytes = 15 << 20 // 15 MiB, ~20 MiB once encoded

LLMMaxAttachmentBytes is the total attachment size one request may carry.

It is a guard, not a provider limit: the real ceilings differ (Anthropic 32MB per request, OpenAI and Google around 20MB) and they apply *after* base64 inflates the payload by a third. Failing here names the problem; failing at the provider returns a size error against a request that also had a prompt in it, several seconds and one billed round trip later.

Variables

View Source
var ErrBodyTooLarge = errors.New("http: request body too large")

ErrBodyTooLarge is wrapped by the error a request gets when its body exceeds the limit in force. Compare with errors.Is(err, core.ErrBodyTooLarge).

View Source
var ErrCacheDisabled = errors.New("cache: not configured")

ErrCacheDisabled is wrapped by the error returned when an operation needs a real cache and none is configured (subscribing to pub/sub, for instance). Reads and writes never return it — they degrade to a miss.

View Source
var ErrCacheMiss = errors.New("cache: miss")

ErrCacheMiss is wrapped by the error returned when a key is absent. Compare with errors.Is(err, core.ErrCacheMiss).

View Source
var ErrChatDisabled = errors.New("chat: not configured")

ErrChatDisabled is wrapped by the error every operation returns when no chat provider is configured.

Chat does not degrade quietly, for the same reason mail does not: an alert that was silently dropped is an incident nobody was told about, and the log says nothing either — the whole point of the message was to be the thing somebody reads.

View Source
var ErrDocumentNotFound = errors.New("mongo: document not found")

ErrDocumentNotFound is wrapped by the error a read returns when nothing matches. Compare with errors.Is(err, core.ErrDocumentNotFound).

View Source
var ErrDuplicateKey = errors.New("mongo: duplicate key")

ErrDuplicateKey is wrapped by the error a write returns when it collides with a unique index — the "this email is already registered" case, which is a conflict to answer rather than a failure to report.

View Source
var ErrEmbedUnsupported = errors.New("embed: capability not supported")

ErrEmbedUnsupported is wrapped by the error a driver returns when the request asks for something the chosen embedding model cannot do — the counterpart of ErrLLMUnsupported, and distinct from a disabled model for the same reason: one is fixed by configuration, the other by picking another model or dropping the field.

View Source
var ErrEmbedderDisabled = errors.New("embed: not configured")

ErrEmbedderDisabled is wrapped by the error every operation returns when no embedding model is configured.

Like the language model and unlike the cache, it fails loudly: an empty vector is not a degraded answer, it is a search index that will quietly return nothing relevant forever.

View Source
var ErrLLMDisabled = errors.New("llm: not configured")

ErrLLMDisabled is wrapped by the error every operation returns when no AI_* configuration is set.

The model does not degrade the way the cache does. A cache miss is recoverable — the value is recomputed — but a generation that quietly returned nothing is an empty answer the caller believes is real, so a service with no provider fails loudly instead.

View Source
var ErrLLMUnsupported = errors.New("llm: capability not supported")

ErrLLMUnsupported is wrapped by the error a driver returns when the request asks for something the chosen model cannot do.

It is a distinct sentinel because the caller's remedy is different: a disabled model is fixed by configuration, an unsupported feature by picking another model or dropping the field.

View Source
var ErrLockLost = errors.New("cache: lock lost")

ErrLockLost is wrapped by the error Extend returns when the lock has expired or been taken over — the work it was guarding is no longer protected.

View Source
var ErrLockNotAcquired = errors.New("cache: lock not acquired")

ErrLockNotAcquired is wrapped by the error Lock returns when somebody else holds the lock. Compare with errors.Is(err, core.ErrLockNotAcquired).

View Source
var ErrMQClosed = errors.New("mq: closed")

ErrMQClosed is wrapped by the error a publish returns after the publisher has been closed — normally because the App is shutting down.

View Source
var ErrMQDisabled = errors.New("mq: not configured")

ErrMQDisabled is wrapped by the error every operation returns when no MQ_* configuration is set.

The queue does not degrade the way the cache does. A cache miss is recoverable — the value is recomputed — but a message that is quietly dropped is work the caller believes it handed off and nobody will ever pick up, so a service with no broker fails loudly instead. This is the same trade-off storage makes.

View Source
var ErrMQNack = errors.New("mq: nacked by broker")

ErrMQNack is wrapped by the error a publish returns when the broker accepted the message and then refused it. It means the message was *not* stored, and the caller has to decide what to do about that.

View Source
var ErrMQNoRoute = errors.New("mq: no queue is bound for the routing key")

ErrMQNoRoute is wrapped by the error a mandatory publish returns when the broker could route the message nowhere.

View Source
var ErrMailerDisabled = errors.New("mailer: not configured")

ErrMailerDisabled is wrapped by the error every operation returns when no EMAIL_* configuration is set.

Mail does not degrade quietly. A password reset that was silently dropped is a user locked out, with nothing in the logs to say why.

View Source
var ErrMongoDisabled = errors.New("mongo: not configured")

ErrMongoDisabled is wrapped by the error every operation returns when no DB_MONGO_* configuration is set. Like storage and unlike the cache, Mongo does not degrade quietly: a read that silently returns nothing, or a write that silently goes nowhere, is worse than a clear failure.

View Source
var ErrObjectNotFound = errors.New("storage: object not found")

ErrObjectNotFound is wrapped by the error returned when a key is absent. Compare with errors.Is(err, core.ErrObjectNotFound).

View Source
var ErrPushDisabled = errors.New("push: not configured")

ErrPushDisabled is wrapped by the error every operation returns when no Firebase credentials are configured.

View Source
var ErrPushUnregistered = errors.New("push: token is not registered")

ErrPushUnregistered is wrapped by a per-token failure that means the token is dead — the app was uninstalled, or the token was replaced. Delete it.

if errors.Is(res.Error, core.ErrPushUnregistered) {
    _ = repo.DeleteToken(res.Token)
}
View Source
var ErrQueueClosed = New(http.StatusServiceUnavailable, "QUEUE_CLOSED", "job queue is closed")

ErrQueueClosed is returned by a closed queue.

View Source
var ErrStorageDisabled = errors.New("storage: not configured")

ErrStorageDisabled is wrapped by the error every operation returns when no S3_* configuration is set.

Storage does not degrade the way the cache does. A cache miss is recoverable — the value is recomputed — but an upload that is quietly dropped is a file the caller believes it saved and nobody can get back, so a service with no bucket fails loudly instead.

View Source
var ShutdownSignals = []os.Signal{os.Interrupt, syscall.SIGTERM}

ShutdownSignals is what a running service is asked to stop with.

SIGTERM is the one that matters in production: it is what `docker stop`, Kubernetes and systemd send, and a process that does not listen for it is killed outright after the grace period — in-flight requests included. SIGINT is Ctrl-C, which is the same event from a terminal.

Functions

func BodyLimit

func BodyLimit(limit int64) echo.MiddlewareFunc

BodyLimit rejects a request whose body is larger than limit bytes with a 413 REQUEST_TOO_LARGE. It checks the declared Content-Length and the bytes actually read, so a chunked upload that declares no size is stopped as it streams rather than after all of it has arrived.

NewHTTPServer installs one for the whole server. Use this to give a route or a group a limit of its own — larger or smaller, because the limit is resolved when the body is read and the innermost one has set it by then:

e.POST("/avatars", h.Upload, core.BodyLimit(50<<20))

func BoolPtr

func BoolPtr(b bool) *bool

BoolPtr is a helper for JobDef.Replayable.

func CosineSimilarity

func CosineSimilarity(a, b []float32) float64

CosineSimilarity is how close two vectors point in the same direction: 1 is identical, 0 unrelated, -1 opposite.

It lives here because every caller of an embedder needs it and it is the one piece of vector arithmetic that is easy to get wrong — forgetting to normalise turns a similarity score into a magnitude comparison, which ranks long documents above relevant ones.

Vectors of different lengths return 0: they came from different models, and any number would be meaningless.

func EmbeddedTexts

func EmbeddedTexts(e IEmbedder) []string

EmbeddedTexts returns what a memory embedder was asked to embed, in order. It returns nil for any other embedder.

func Forget

func Forget(c ICache, keys ...string)

Forget removes keys, ignoring a cache that is unavailable. It is the invalidation half of Remember, for use in a write path that must not fail because the cache is down.

func Get

func Get[T any](ctx IContext, key string) (T, bool)

Get retrieves a typed value previously stored with Set (or SetData).

func LockWait

func LockWait(c ICache, key string, ttl, wait time.Duration) (ILock, IError)

LockWait acquires a lock, waiting up to wait for a turn. It gives up with an ErrLockNotAcquired error rather than blocking forever, so a jammed lock shows up as a failed request instead of an exhausted goroutine pool.

func MongoAggregatePage

func MongoAggregatePage[T any](m IMongoDB, collection string, pipeline []map[string]any,
	opts *PageOptions, aggOpts ...MongoAggregateOptions,
) (*Page[T], IError)

MongoAggregatePage runs a pipeline for the page and for the count.

Use it when the list being paged is the output of a pipeline rather than of a filter — a join, a computed field, a grouping. Pass the pipeline *without* $skip/$limit; they are appended.

A page of up to mongoFacetPageLimit comes back in one round trip via $facet, so the count cannot drift from the items. A larger page would not fit in the one document $facet builds, so it costs two round trips and the count is read from a collection that may have changed in between.

func MongoByID

func MongoByID(id string) bson.M

MongoByID is the _id filter for a hex id, falling back to the raw value for a collection whose ids are strings of your own making:

err := ctx.DBMongo().FindOne(&user, "users", core.MongoByID(id))

func MongoPaginate

func MongoPaginate[T any](m IMongoDB, collection string, filter any, opts *PageOptions) (*Page[T], IError)

MongoPaginate runs a counted, sorted, limited query and returns a Page — the Mongo counterpart of Paginate for SQL.

page, err := core.MongoPaginate[User](ctx.DBMongo(), "users",
    bson.M{"status": "active"}, c.GetPageOptions())

An unfiltered page — the first screen of a list with no search applied, which is the most requested page there is — takes its total from the collection's metadata instead of counting. See mongoFilterMatchesEverything for what that costs.

func MongoSortDocument

func MongoSortDocument(fields []string) bson.D

MongoSortDocument turns the "-created_at" spelling used by PageOptions and MongoFindOptions into the driver's sort document, for code building a $sort stage by hand.

func NewApp

func NewApp(env IENV, opts ...Option) (*App, IError)

NewApp builds the application container from configuration and options.

func NewCSVWriter

func NewCSVWriter[T any](w io.Writer, opts ...CSVOptions) (*CSVWriter[T], IError)

NewCSVWriter starts a CSV file: it writes the BOM and the header immediately, so a caller that writes no rows still produces a valid file.

func NewCache

func NewCache(env IENV, opts ...CacheOption) (ICache, IError)

NewCache connects to Redis using configuration and returns a ready ICache. It accepts a full URI (CACHE_CONNECTION_STRING, e.g. "redis://user:pass@host:6379/0" or "rediss://..."), a comma-separated node list (CACHE_ADDRS, for cluster), a sentinel master (CACHE_MASTER_NAME), or the discrete CACHE_HOST/CACHE_PORT/CACHE_USERNAME/CACHE_PASSWORD/CACHE_DB fields.

It fails fast: the connection is verified with a PING before it is returned, so a misconfigured cache is a boot error rather than a surprise on the first request.

func NewEnv

func NewEnv() (IENV, IError)

NewEnv loads configuration from the current directory (.env, or test.env when APP_ENV=test) plus APP_-prefixed environment variables.

func NewEnvPath

func NewEnvPath(path string) (IENV, IError)

NewEnvPath loads configuration from a specific directory.

func NewGormLogger

func NewGormLogger(log ILogger, level gormlogger.LogLevel, slowQuery time.Duration) gormlogger.Interface

NewGormLogger builds the gorm logger used by NewDatabase. Pass it to gorm.Open directly when opening a connection by hand.

func NewMQ

func NewMQ(env IENV, opts ...MQOption) (IMQ, IError)

NewMQ connects to RabbitMQ using configuration and returns an IMQ publisher. It accepts either a full URI (MQ_CONNECTION_STRING, e.g. "amqp://user:pass@host:5672/vhost" or "amqps://...") or discrete MQ_HOST/MQ_PORT/MQ_USER/MQ_PASSWORD fields.

The returned publisher survives a broker restart: it reopens the connection and its channels on the first publish after the old ones died, so a service does not have to be restarted along with its broker.

func NewMailTemplates

func NewMailTemplates(fsys fs.FS, opts ...MailTemplateOptions) (*MailTemplates, IError)

NewMailTemplates parses an fs.FS of templates. Files ending in .html (or .gohtml) join the HTML set and .txt (or .gotxt) the text set, keyed by the path without its extension — so "welcome.html" and "welcome.txt" are the two bodies of the template "welcome".

//go:embed templates/email
var emailFS embed.FS

tpl, err := core.NewMailTemplates(emailFS, core.MailTemplateOptions{Root: "templates/email"})
mailer, err := core.NewMailer(env, core.WithMailTemplates(tpl))

Everything parses into one set, so a shared layout or a partial defined in one file is usable from every other.

func NewMailer

func NewMailer(env IENV, opts ...MailerOption) (IMailer, IError)

NewMailer builds an SMTP mailer from configuration.

EMAIL_SERVER=smtp.example.com
EMAIL_PORT=587
EMAIL_USERNAME=... EMAIL_PASSWORD=...
EMAIL_SENDER=no-reply@example.com
EMAIL_SENDER_NAME=Example
EMAIL_TLS_POLICY=mandatory   # mandatory (default) | opportunistic | none
EMAIL_SSL=false              # implicit TLS, for port 465
EMAIL_AUTH=auto              # plain | login | cram-md5 | xoauth2 | none | auto
EMAIL_TIMEOUT=30             # seconds

func NewModules

func NewModules(mods ...IModule) (*ModuleSet, IError)

NewModules assembles the modules of a service, rejecting a duplicate or malformed name straight away.

mods, err := core.NewModules(
    home.New(),
    auth.New(usersFor),
    note.New(usersFor),
)

There is deliberately no global registry and no init()-time registration: this call is the one place that knows every module, which is what lets a test assemble the real service minus one module, and what keeps a module's dependencies (the interfaces it declares and the composition root supplies) passable at all — an init function takes no arguments.

func NewMongoDB

func NewMongoDB(env IENV, opts ...MongoOption) (IMongoDB, IError)

NewMongoDB connects to MongoDB using configuration and returns an IMongoDB. It accepts a full URI (DB_MONGO_CONNECTION_STRING) or the discrete DB_MONGO_HOST/PORT/USERNAME/PASSWORD fields, which now also honour DB_MONGO_REPLICA_NAME and DB_MONGO_TLS.

Every command is logged the way SQL statements are — failures, then slow commands, then everything at debug — carrying the request the command belongs to. See DB_MONGO_LOG_LEVEL. Alongside the commands it logs the two things the commands cannot show: a connection checkout that failed, and the primary moving. See NewMongoPoolMonitor and NewMongoServerMonitor.

It fails fast: the database name is required and the connection is verified with a ping, so a misconfigured Mongo is a boot error rather than a surprise on the first query.

func NewMongoMonitor

func NewMongoMonitor(log ILogger, level MongoLogLevel, slowQuery time.Duration) *event.CommandMonitor

NewMongoMonitor builds the command monitor used by NewMongoDB. Pass it to options.Client().SetMonitor when opening a connection by hand.

It returns nil at MongoLogSilent: a monitor that records events and drops them still costs a map write and a document render per command.

func NewMongoPoolMonitor

func NewMongoPoolMonitor(log ILogger, level MongoLogLevel) *event.PoolMonitor

NewMongoPoolMonitor builds the connection-pool monitor used by NewMongoDB. Pass it to options.Client().SetPoolMonitor when opening a connection by hand.

Of the eleven pool events it logs two. A pool being created, becoming ready, or handing a connection out and taking it back says nothing the command log does not already say, and at a pair per operation it would bury it. The two that are kept are the ones that only happen when something is wrong and that nothing else in the log accounts for:

  • a checkout that failed — the pool is exhausted or the server is unreachable. This is the failure that is invisible today: the time goes into waiting for a connection rather than running a command, so every query is slow and the slow-command log stays empty.
  • a pool that was cleared — the driver threw away every connection to a server it decided is unhealthy, which is what a failover looks like from the client.

Both are rare enough to leave on in production, which is the point: the evidence has to already be in the log when someone comes to read it, because the moment to turn on debug logging is the moment nobody is there to do it.

Unlike the command monitor, pool events carry no context, so these lines cannot name the request that was waiting.

func NewMongoServerMonitor

func NewMongoServerMonitor(log ILogger, level MongoLogLevel) *event.ServerMonitor

NewMongoServerMonitor builds the topology monitor used by NewMongoDB. Pass it to options.Client().SetServerMonitor when opening a connection by hand.

It answers one question the rest of the log cannot: was the deployment itself the problem. A member going unreachable and a primary moving are what turn into "server selection timeout" and "not primary" further up, where the cause is no longer visible.

Heartbeats are deliberately not logged. A node that is down fails one every few seconds, and the same line repeated forever is not information; the description changing to Unknown says it once.

func NewPusher

func NewPusher(credentialJSON string, opts ...PusherOption) (IPusher, IError)

NewPusher builds an FCM client. credentialJSON is the service-account JSON (ENVConfig.FirebaseCredential); pass an empty string to use the machine's ambient Google credentials, which is what a workload identity provides.

func NewPusherFromEnv

func NewPusherFromEnv(env IENV, opts ...PusherOption) (IPusher, IError)

NewPusherFromEnv builds a pusher from FIREBASE_CREDENTIAL.

func NewRecordingSentry

func NewRecordingSentry(env IENV, opts ...SentryOptions) (ISentry, *SentryRecorder, IError)

NewRecordingSentry builds a fully working tracker whose events are kept in memory. Everything else — scrubbing, scope, fingerprints, breadcrumbs — runs exactly as it does in production, which is what makes the assertions worth anything.

func NewRedisLimiter

func NewRedisLimiter(app *App, opts ...LimiterOption) (ILimiter, IError)

NewRedisLimiter builds a limiter shared by every replica, so JobDef MaxConcurrent and queue limits hold across the cluster instead of per process:

lim, err := core.NewRedisLimiter(app)
runner := core.NewJobRunner(app, reg, core.WithJobLimiter(lim))

It fails when the App has no redis-backed cache, rather than quietly counting in one process: a `MaxConcurrent: 1` job that silently runs once per replica is the bug this type exists to prevent. A single-replica service wants NewInProcessLimiter (the default) and needs no redis at all.

func NewScheduler

func NewScheduler(app *App, opts ...SchedulerOption) (*Scheduler, IError)

NewScheduler builds a scheduler. Called with no runner — as in v1 — it creates a self-contained one (in-memory queue and store) and manages its lifecycle, so a service that only wants cron jobs needs nothing else:

sc, _ := core.NewScheduler(app)
sc.AddByCron("nightly", "0 2 * * *", NightlyReport)
sc.Start()

Pass an existing runner to share it with the rest of the service (manual triggers, an admin API, a durable store), and WithSchedulerLocation to fix the zone every schedule is read in.

func NewSentry

func NewSentry(env IENV, opts ...SentryOptions) (ISentry, IError)

NewSentry builds the error tracker from configuration. With no DSN it returns a no-op tracker, so wiring is unconditional: every service can call ctx.Sentry() and only the DSN decides whether anything is sent.

sentryTracker, err := core.NewSentry(env)
app, err := core.NewApp(env, core.WithSentry(sentryTracker))

NewApp does this for you when no tracker is supplied.

func NewStorage

func NewStorage(env IENV, opts ...StorageOption) (IStorage, IError)

NewStorage builds an S3-compatible storage client from configuration.

Credentials come from S3_ACCESS_KEY/S3_SECRET_KEY when both are set, and otherwise from the AWS default chain — which is what lets a deployment on EKS or EC2 use an instance role and set no keys at all. (v2.2 always installed static credentials, so an empty pair silently overrode the role and every call failed to sign.)

func ParseOrderBy

func ParseOrderBy(s string, allowed []string) []string

ParseOrderBy turns an order_by query parameter into GORM order clauses, dropping anything that is not a column identifier and — when allowed is non-nil — any column not in it.

Two spellings, both from v1, may be mixed in one parameter:

name                     → "name desc"      (desc is the default direction)
age asc                  → "age asc"
asc(age)                 → "age asc"        (bracket form)
desc(name),created_at    → "name desc", "created_at desc"

Any function name other than asc means desc, matching v1: "abc(name)" sorts name descending rather than failing.

GetPageOptions calls this for you. Reach for it directly when the order comes from somewhere other than the query string, or when you have rewritten the parameter first — passing hand-built strings straight into PageOptions.OrderBy skips the column check, and GORM will hand whatever is there to the driver.

func PushTopicTokens

func PushTopicTokens(p IPusher, topic string) []string

PushTopicTokens returns the tokens a memory pusher believes are subscribed to a topic, sorted.

func QueueLLMReply

func QueueLLMReply(l ILLM, replies ...MemoryLLMReply)

QueueLLMReply appends scripted replies to a memory model — for usage numbers or a failure, which NewMemoryLLM's plain strings cannot express. It is a no-op for any other model.

func Recover

func Recover(dst *error)

Recover converts a panic into an *Error stored in *dst, preserving a stack trace. Unlike v1's Recover (which re-panicked with a new string and discarded the stack), this lets a deferred call turn a panic into a normal error return.

func doWork() (err error) {
    defer core.Recover(&err)
    // ... code that may panic ...
    return nil
}

func RegisterHealthRoutes

func RegisterHealthRoutes(e *Server, opts ...HealthOptions)

RegisterHealthRoutes adds the two probes every deployment needs, at the paths Kubernetes uses by default. They are registered before any authentication — call it on the server, not on an authenticated group.

func RequestID

func RequestID(ctx context.Context) string

RequestID is the id of the request or job run ctx belongs to, or "".

It is what correlates a log line, a Sentry event and a trace entry with each other. The framework puts it on the context in its own middleware; this is for application code that wants to carry it somewhere else — a downstream call, a row in an audit table, a support reply that says which request to look at.

func Requeue

func Requeue(err error) error

Requeue wraps a handler's error to ask the broker to deliver the message again, instead of dead-lettering it.

Use it for a failure that is about *now* — a database that is down, a rate limit — and not for one that will fail again in the same way. A message requeued for a permanent failure comes straight back, and the loop it forms is the most common way an AMQP consumer melts down. Reach for a dead-letter queue instead.

func ResetChatMessages

func ResetChatMessages(c IChat)

ResetChatMessages drops everything a memory provider has recorded.

func ResetLLM

func ResetLLM(l ILLM)

ResetLLM drops everything a memory model has recorded and rewinds its scripted replies.

func ResetMail

func ResetMail(m IMailer)

ResetMail drops everything a memory mailer has recorded.

func ResetPushes

func ResetPushes(p IPusher)

ResetPushes drops everything a memory pusher recorded, subscriptions included.

func RootCause

func RootCause(err error) error

RootCause walks an error chain to its deepest error: the failure as the driver, syscall or library reported it, rather than any wrapper placed around it on the way up.

func StartHTTPServer

func StartHTTPServer(e *Server, env IENV)

StartHTTPServer runs the server and blocks.

Outside dev it drains on SIGINT/SIGTERM — new connections refused, in-flight requests given DefaultGracefulTimeout to finish — and then closes the App's pools, in that order, because a pool closed while a request still holds it turns a clean shutdown into a burst of 500s.

It is the HTTP-only starter. A process that also runs jobs owns its own shutdown, so that the scheduler stops between the two steps above: see [Lifecycle & roles](./docs/lifecycle.md).

func WithHTTPContext

func WithHTTPContext(app *App, h HandlerFunc) echo.HandlerFunc

WithHTTPContext adapts an mine-core handler to echo, constructing the per-request context from the App (pools are not recreated per request). If an auth middleware has resolved a user, it is attached so c.GetUser() works.

func WithRequestID

func WithRequestID(ctx context.Context, id string) context.Context

WithRequestID returns ctx carrying id, so everything logged under it is correlated with the request it came from.

The HTTP middleware already does this for a request. This is for the work that leaves one — a goroutine started to finish something after the response, a message published and consumed elsewhere — where the correlation is the only thing connecting the two halves of one story.

Types

type AckFunc

type AckFunc func(err error)

AckFunc finalises a reserved run. Pass nil when the runner has dealt with the run (its final status is already persisted); pass an error when delivery itself failed, so the queue can make the run available again.

type App

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

App owns the long-lived resources (connection pools, base logger, shared HTTP client). It is built once at startup; per-request contexts derive from it. This fixes v1's bug where IContext.Close() tore down shared pools per request.

func (*App) Cache

func (a *App) Cache(name ...string) ICache

Cache returns a registered cache, "default" when called without a name. Never nil: an unregistered name gives the disabled cache. Prefer ctx.Cache(), which is bound to the request or run.

func (*App) Capabilities

func (a *App) Capabilities() []Capability

Capabilities lists every capability of this App, ordered by kind and then by connection name so two readings can be compared.

Nothing here does I/O — it reports what was wired, not what is reachable. Use CheckHealth for the second question.

func (*App) Chat

func (a *App) Chat(name ...string) IChat

Chat returns a registered chat provider, "default" when called without a name. Never nil: an unregistered name gives the disabled provider, whose every call fails with CHAT_DISABLED.

Inside a request or a job use core.Chat(ctx) / core.Chats(ctx, name), which bind the post to that unit of work.

func (*App) Config

func (a *App) Config() *ENVConfig

Config returns the loaded configuration.

func (*App) ENV

func (a *App) ENV() IENV

ENV returns the environment accessor.

func (*App) LLMModel

func (a *App) LLMModel() ILLM

LLMModel returns the language model, unbound to any request — for a startup check, or a background goroutine that outlives one. Never nil: without a provider every call fails with LLM_DISABLED.

Inside a request or a job use core.LLM(ctx), which binds the generation to that unit of work so it is cancelled with it. The name avoids colliding with the core.LLM function, which is what almost every call site should use.

func (*App) Log

func (a *App) Log() ILogger

Log returns the base logger.

func (*App) LogCapabilities

func (a *App) LogCapabilities()

LogCapabilities states what this process was actually wired with.

Every capability degrades rather than refusing to boot: no CACHE_* gives a cache that misses, no S3_* gives storage that errors, an unregistered Mongo name gives a disabled handle. That is deliberate — a service should not fail to start over something it may never touch — but it means a missing connection is invisible until the first request that needed it, and the symptom then ("nothing is being cached", "the queue never gets anything") is several layers away from the cause, which is one line of configuration.

One line at boot answers it. Named connections are listed by name so that "which replica did it open?" is answerable too.

StartHTTPServer and Runner call it, so a service using either gets it for free. It is exported for a process that starts itself some other way — and it is deliberately not called by NewApp, because building the container is not the same event as starting the process, and every test builds one.

func (*App) MQ

func (a *App) MQ() IMQ

MQ returns the message-queue publisher. Never nil: without a broker every call fails with MQ_DISABLED. Prefer ctx.MQ(), which is bound to the request or run and so is cancelled with it.

func (*App) Mailer

func (a *App) Mailer() IMailer

Mailer returns the mailer, unbound to any request — for a startup check, or a background goroutine that outlives one. Never nil: without an SMTP server every call fails with MAILER_DISABLED.

Inside a request or a job use core.Mailer(ctx), which binds the delivery to that unit of work.

func (*App) Meter

func (a *App) Meter() IMeter

Meter records measurements outside any request or run — at boot, in a background goroutine. Inside one, use ctx.Meter() so the measurement carries that unit of work's trace.

func (*App) NewContext

func (a *App) NewContext(ctx context.Context, mode ...Mode) IContext

NewContext derives a per-request/job context bound to ctx. mode defaults to ModeHTTP when omitted.

func (*App) NewMQConsumer

func (a *App) NewMQConsumer(opts ...MQConsumerOption) IMQConsumer

NewMQConsumer builds a consumer on the App's broker configuration. Nothing connects until Start, so handlers can be registered in any order.

The App remembers it and stops it during Shutdown, before the connections its handlers use are closed.

func (*App) NewSubscriber

func (a *App) NewSubscriber(opts ...SubscriberOption) ISubscriber

NewSubscriber builds a subscriber on one of the App's caches. Nothing is subscribed until Start, so handlers can be registered in any order.

The App remembers it and stops it during Shutdown, before the connections it is reading from are closed.

func (*App) PubSub

func (a *App) PubSub() IPubSub

PubSub is the publish/subscribe side of the default cache. Never nil.

func (*App) Pusher

func (a *App) Pusher() IPusher

Pusher returns the push sender, unbound to any request. Never nil: without Firebase credentials every call fails with PUSH_DISABLED.

Inside a request or a job use core.Pusher(ctx).

func (*App) Sentry

func (a *App) Sentry() ISentry

Sentry returns the process-wide error tracker. Prefer ctx.Sentry(), which is bound to the request or run and therefore reports far more context.

func (*App) Shutdown

func (a *App) Shutdown(ctx context.Context) IError

Shutdown closes the owned pools. Safe to call more than once: the second call is a no-op, so a `defer app.Shutdown(ctx)` and StartHTTPServer's own close can coexist.

Call it after everything that uses a pool has stopped — requests drained, jobs finished — never before.

func (*App) Storage

func (a *App) Storage() IStorage

Storage returns object storage. Never nil: without a bucket every call fails with STORAGE_DISABLED. Prefer ctx.Storage(), which is bound to the request or run and so is cancelled with it.

type Attachment

type Attachment struct {
	// Name is the filename the recipient sees.
	Name string
	// Content is the file, in memory.
	Content []byte
	// Reader streams the file instead of holding it in memory — an S3 object, a
	// generated report. It is read once, when the message is sent.
	Reader io.Reader
	// ContentType defaults to being guessed from Name.
	ContentType string
	// ContentID makes an inline part referenceable from the HTML body as
	// <img src="cid:the-id">. Put the file in Embeds rather than setting this by
	// hand; the name is used when it is empty.
	ContentID string
}

Attachment is a file sent with a message. Give it Content or Reader, not both.

type Auth

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

Auth authenticates bearer tokens with a TokenVerifier and exposes echo middleware.

func NewAuth

func NewAuth(verify TokenVerifier, opts ...AuthOption) *Auth

NewAuth builds an Auth from a custom TokenVerifier — use it for opaque tokens (API keys, sha256/random tokens looked up in a store) or a chain of strategies.

func NewJWTAuth

func NewJWTAuth(secret string, opts ...AuthOption) *Auth

NewJWTAuth is the convenience for HS256 JWT bearer auth.

func (*Auth) Middleware

func (a *Auth) Middleware() echo.MiddlewareFunc

Middleware requires a valid bearer token; otherwise it returns 401. On success the user is available in handlers via c.GetUser().

func (*Auth) Optional

func (a *Auth) Optional() echo.MiddlewareFunc

Optional validates the token when present but allows anonymous requests.

func (*Auth) RequireRole

func (a *Auth) RequireRole(roles ...string) echo.MiddlewareFunc

RequireRole allows the request only when the authenticated user's Segment (role) is one of roles. Chain it after Middleware.

func (*Auth) SignToken

func (a *Auth) SignToken(claims jwt.MapClaims, ttl time.Duration) (string, IError)

SignToken issues a JWT with this Auth's secret. Requires an Auth built with NewJWTAuth.

type AuthOption

type AuthOption func(*authConfig)

AuthOption configures an Auth.

func WithTokenLookup

func WithTokenLookup(fn func(ec *echo.Context) string) AuthOption

WithTokenLookup overrides how the token is extracted from the request (default: the "Authorization: Bearer <token>" header).

func WithUserResolver

func WithUserResolver(r UserResolver) AuthOption

WithUserResolver overrides how JWT claims become a ContextUser (JWT auth only).

type BackoffFunc

type BackoffFunc func(attempt int) time.Duration

BackoffFunc returns how long to wait before the given attempt (1-based, so attempt 2 is the first retry).

func ExponentialBackoff

func ExponentialBackoff(base, max time.Duration) BackoffFunc

ExponentialBackoff doubles base each attempt, capped at max.

type BatchResult

type BatchResult struct {
	SuccessCount int
	FailureCount int
	Results      []PushResult
}

BatchResult summarises a multi-token send.

func (*BatchResult) UnregisteredTokens

func (b *BatchResult) UnregisteredTokens() []string

UnregisteredTokens are the tokens the provider rejected as dead. Delete them: they will never work again, and a store full of them turns every broadcast into a slow one.

type Breadcrumb struct {
	// Type is the rendering hint: "default", "http", "query", "navigation", "error".
	Type string
	// Category groups related crumbs, e.g. "http.client", "db", "mq".
	Category string
	Message  string
	Level    Level
	Data     map[string]any
}

Breadcrumb is one step of the trail that led to an event. Breadcrumbs are recorded on the context's hub, so they are per-request/per-run — never shared between concurrent requests the way v1's global scope was.

type CSVOptions

type CSVOptions struct {
	// BOM writes a UTF-8 byte-order mark before the header. Turn it on for a
	// file a person will open in Excel; leave it off for one another program
	// will parse.
	BOM bool
	// Comma is the field separator (default ',').
	Comma rune
	// TimeLayout is the layout time values are formatted and parsed with
	// (default DefaultCSVTimeLayout). On reading it is tried first, then RFC
	// 3339 and the plain date, so a file exported by a spreadsheet still loads.
	TimeLayout string
	// NoHeader writes no header row, and on reading treats the first row as
	// data mapped to the struct's fields in order.
	NoHeader bool
}

CSVOptions tunes marshalling and unmarshalling. The zero value is the default behaviour: comma-separated, RFC 3339 times, no BOM.

type CSVWriter

type CSVWriter[T any] struct {
	// contains filtered or unexported fields
}

CSVWriter streams rows to a CSV file without holding them all in memory — for an export whose size is the database's business rather than the process's.

cw, err := core.NewCSVWriter[Row](w, core.CSVOptions{BOM: true})
for _, batch := range batches {
    if err := cw.Write(batch...); err != nil { return err }
}
return cw.Flush()

func (*CSVWriter[T]) Flush

func (c *CSVWriter[T]) Flush() IError

Flush writes anything buffered and reports the first error of the whole file.

func (*CSVWriter[T]) Write

func (c *CSVWriter[T]) Write(rows ...T) IError

Write appends rows. Nothing is guaranteed to have reached w until Flush.

type CacheOption

type CacheOption func(*cache)

CacheOption tunes a cache at construction.

func WithCachePrefix

func WithCachePrefix(prefix string) CacheOption

WithCachePrefix namespaces every key of the cache being built. It overrides CACHE_PREFIX.

type Capability

type Capability struct {
	// Kind is what this is: "sql", "mongo", "cache", "chat", "mq", "storage",
	// "mailer", "pusher", "llm", "embedder", "sentry".
	Kind string `json:"kind"`
	// Name is the connection name for the kinds that have several ("default",
	// "replica"), empty for the ones a process has at most one of.
	Name string `json:"name,omitempty"`
	// Enabled is false for the disabled implementation a missing configuration
	// gives — the whole point of the list, since that one never fails to build.
	Enabled bool `json:"enabled"`
	// Detail identifies what is on the other end, in terms that carry no
	// credentials: a driver, a database name, a model.
	Detail string `json:"detail,omitempty"`
	// Stats is live counters, currently only the SQL pool's.
	Stats map[string]any `json:"stats,omitempty"`
}

Capability is one dependency this process was wired with, in a shape something other than a log line can read.

It answers the question LogCapabilities answers at boot — "does this process actually have a cache?" — at any later moment, and with the pool numbers a boot line cannot have: a service whose requests are queueing on a full connection pool looks identical, from the outside, to one whose database is slow.

type CaptureOption

type CaptureOption func(*captureOptions)

CaptureOption tunes a single capture.

func CaptureContext

func CaptureContext(name string, data map[string]any) CaptureOption

CaptureContext attaches a named block of structured data to this event.

func CaptureExtra

func CaptureExtra(key string, value any) CaptureOption

CaptureExtra attaches a non-indexed value to this event.

func CaptureFingerprint

func CaptureFingerprint(parts ...string) CaptureOption

CaptureFingerprint overrides how Sentry groups this event into an issue. Include "{{ default }}" to keep the stack-trace grouping and only split on the extra parts.

func CaptureLevel

func CaptureLevel(l Level) CaptureOption

CaptureLevel overrides the severity derived from the error's status.

func CaptureTag

func CaptureTag(key, value string) CaptureOption

CaptureTag adds one indexed tag to this event.

func CaptureTags

func CaptureTags(tags map[string]string) CaptureOption

CaptureTags adds several indexed tags to this event.

type ChatField

type ChatField struct {
	Name  string
	Value string
	// Inline asks the provider to put this field beside the next one rather than
	// on its own row. It is a request, not a guarantee: a provider that has no
	// such layout ignores it.
	Inline bool
}

ChatField is one labelled value in a message — "order", "12345". Fields are what makes an alert scannable: the same keys in the same order every time, rather than a sentence that has to be read.

type ChatLevel

type ChatLevel uint8

ChatLevel is how serious a message is. A provider renders it as whatever it has — a colour bar on Slack, an embed colour on Discord — so the same alert reads the same way wherever it is sent.

const (
	// ChatInfo is the default: something happened worth saying.
	ChatInfo ChatLevel = iota
	// ChatSuccess is something that finished the way it was meant to.
	ChatSuccess
	// ChatWarn is something that still worked but should not be ignored.
	ChatWarn
	// ChatError is something that failed.
	ChatError
)

func (ChatLevel) String

func (l ChatLevel) String() string

String is the level's name, for a log line or a test assertion.

type ChatLink struct {
	Text string
	URL  string
}

ChatLink is a labelled URL — the run that failed, the dashboard to look at.

type ChatMessage

type ChatMessage struct {
	// To is the destination: a channel ("#ops" or "C0123ABCD" on Slack), a user,
	// a group. Empty uses whatever the provider was configured with.
	To string

	// Title is the headline; Text is the body. Either may be empty, but a message
	// with no body at all is rejected before it is sent.
	Title string
	Text  string

	Level  ChatLevel
	Fields []ChatField
	Links  []ChatLink

	// ThreadID replies inside an existing thread. It is the ID a previous Send
	// returned — how a job posts "started" once and then hangs its progress off
	// that message instead of filling the channel.
	ThreadID string

	// Native is the provider's own request body, used as it is. It wins over
	// every field above except To and ThreadID, which are still filled in when
	// the payload does not already carry them.
	//
	// A message carrying Native is written against one provider and is not
	// portable — which is the trade being made, and the reason it is a separate
	// field rather than something that leaks into the rest of the struct.
	Native map[string]any
}

ChatMessage is a message to post.

The fields above Native are the subset every provider can render, so a service that sticks to them can be pointed at another platform by changing configuration. Anything richer — Slack Block Kit, Discord embeds, LINE Flex — goes in Native.

There is deliberately no unified builder for those three. They are genuinely different models of a message, and a common denominator over them would be worse to write against than any of the three, while still needing an escape hatch for everything it failed to cover.

func SentChatMessages

func SentChatMessages(c IChat) []ChatMessage

SentChatMessages returns what a memory provider has recorded, in order. It returns nil for any other provider.

type ChatResult

type ChatResult struct {
	// ID identifies the posted message, when the provider returns one. Pass it
	// back as ChatMessage.ThreadID to reply to it.
	ID string
	// To is the destination that was actually used, which is the configured
	// default when the message named none.
	To string
	// ThreadID is the thread the message landed in, empty when it started one.
	ThreadID string
}

ChatResult is what came back from a successful Send.

type CheckIn

type CheckIn struct {
	// ID pairs a terminal check-in with the in-progress one that opened it.
	// Leave empty on the first report and pass back what CheckIn returned.
	ID       string
	Monitor  string
	Status   CheckInStatus
	Duration time.Duration
	// Schedule tells Sentry when the monitor is expected to run, so a missed run
	// raises an alert. Only cron expressions and intervals are understood.
	Schedule Schedule
	// MaxRuntime marks the run as failed if it does not finish in time.
	MaxRuntime time.Duration
	// CheckInMargin is the grace period before a late run counts as missed.
	CheckInMargin time.Duration
	// Timezone is the zone Schedule's hours are read in when the schedule does
	// not name one itself (CronIn does). Empty means UTC, as Sentry defaults.
	Timezone string
}

CheckIn is one report to a Sentry cron monitor. The scheduler sends these automatically for jobs that have a Schedule (see SentryOptions.EnableCrons).

type CheckInStatus

type CheckInStatus = sentry.CheckInStatus

CheckInStatus is the state reported to a Sentry cron monitor.

type CheckResult

type CheckResult struct {
	Status   string `json:"status"`
	Critical bool   `json:"critical,omitempty"`
	Error    string `json:"error,omitempty"`
	TookMS   int64  `json:"took_ms"`
}

CheckResult is one dependency's answer.

type ConcurrencyPolicy

type ConcurrencyPolicy uint8

ConcurrencyPolicy decides what happens when a run cannot get a concurrency slot for its job or queue.

const (
	// ConcurrencyEnqueue puts the run back on the queue with a short backoff
	// until a slot frees up. Nothing is lost — the default.
	//
	// Careful with frequent cron schedules: if the job takes longer than its
	// interval the queue grows without bound. Use ConcurrencySkip there.
	ConcurrencyEnqueue ConcurrencyPolicy = iota
	// ConcurrencySkip finishes the run immediately as RunSkipped.
	ConcurrencySkip
	// ConcurrencyReplace cancels the currently running run(s) of the job and
	// takes their place ("latest wins").
	ConcurrencyReplace
)

func (ConcurrencyPolicy) String

func (p ConcurrencyPolicy) String() string

String renders a policy for display.

type ConsumeQueue

type ConsumeQueue struct {
	// Queue is declared before consuming. Name is the only required field.
	Queue QueueConfig
	// Exchange, when named, is declared too.
	Exchange *ExchangeConfig
	// BindingKeys bind Queue to Exchange. An empty list with an exchange set
	// binds on "" — which is what a fanout exchange wants.
	BindingKeys []string
}

ConsumeQueue is a queue to consume, together with the topology it needs.

type ContextUser

type ContextUser struct {
	ID       string            `json:"id,omitempty"`
	Email    string            `json:"email,omitempty"`
	Username string            `json:"username,omitempty"`
	Name     string            `json:"name,omitempty"`
	Segment  string            `json:"segment,omitempty"`
	Token    string            `json:"token,omitempty"`
	Data     map[string]string `json:"data,omitempty"`
}

ContextUser is the authenticated principal attached to a context (same shape as v1).

func ContextUserOf

func ContextUserOf(c *echo.Context) *ContextUser

ContextUserOf returns the principal an authentication middleware attached to the request, or nil when the request is anonymous.

It is the read side of what this package's own Auth middleware writes, and what WithHTTPContext copies onto IContext — exported for middleware that runs *before* the framework context exists and so cannot call c.GetUser(). A service whose authentication keeps the user under a key of its own is not visible here; that is the same service that never reads it back through c.GetUser() either.

type DBOption

type DBOption func(*dbOptions)

DBOption configures a database connection.

func WithConnMaxLifetime

func WithConnMaxLifetime(d time.Duration) DBOption

WithConnMaxLifetime sets the max connection lifetime.

func WithDBLogLevel

func WithDBLogLevel(level gormlogger.LogLevel) DBOption

WithDBLogLevel overrides how much SQL is logged, independently of LOG_LEVEL: gormlogger.Info logs every statement, Warn only slow ones and errors, Silent nothing.

db, _ := core.NewDatabase(env, core.WithDBLogLevel(gormlogger.Info))

func WithDBLogger

func WithDBLogger(l ILogger) DBOption

WithDBLogger sends SQL to a specific logger instead of one built from config.

func WithMaxIdleConns

func WithMaxIdleConns(n int) DBOption

WithMaxIdleConns sets the max idle connections.

func WithMaxOpenConns

func WithMaxOpenConns(n int) DBOption

WithMaxOpenConns sets the max open connections.

func WithSlowQuery

func WithSlowQuery(d time.Duration) DBOption

WithSlowQuery sets the duration above which a statement is logged as slow (default 200ms).

type Delivery

type Delivery struct {
	Body        []byte
	Exchange    string
	RoutingKey  string
	Queue       string
	ConsumerTag string

	Headers       map[string]any
	ContentType   string
	MessageID     string
	CorrelationID string
	ReplyTo       string
	Type          string
	AppID         string
	UserID        string
	Priority      uint8
	Timestamp     time.Time

	// Redelivered is set when the broker has handed this message to a consumer
	// before. It is the only hint a handler gets that it may be running twice,
	// and the reason a handler should be idempotent.
	Redelivered bool
	DeliveryTag uint64
}

Delivery is one message a consumer received.

func (*Delivery) Bind

func (d *Delivery) Bind(dest any) IError

Bind decodes the body into dest, following the same rules as ICache.Get: *string, *[]byte and *json.RawMessage take the raw bytes, anything else is JSON-decoded.

func (*Delivery) Header

func (d *Delivery) Header(name string) (any, bool)

Header reads one header.

func (*Delivery) HeaderString

func (d *Delivery) HeaderString(name string) string

HeaderString reads one header as a string, or "" when it is absent or is something else.

type ENVConfig

type ENVConfig struct {
	LogHost   string `koanf:"log_host"`
	LogPort   string `koanf:"log_port"`
	LogLevel  string `koanf:"log_level"`
	LogSimple bool   `koanf:"log_simple"`

	// HTTPLogLevel overrides how much of the *outgoing* HTTP traffic is logged,
	// independently of LOG_LEVEL: "silent" (nothing), "error", "warn" (slow calls
	// and failures — the default), "info"/"debug" (every call).
	HTTPLogLevel string `koanf:"http_log_level"`
	// HTTPLogBody adds the request and response bodies to those lines, scrubbed
	// and truncated. Off by default: a body carries credentials and personal
	// data, and is the easiest way to turn a log store into a place secrets live.
	HTTPLogBody bool `koanf:"http_log_body"`

	Host    string `koanf:"host"`
	ENV     string `koanf:"env"`
	Service string `koanf:"service"`

	// Sentry. Only SentryDSN is required — set it and errors, panics, job
	// failures and breadcrumbs are reported with no further wiring. Everything
	// else tunes what is sent; see docs/sentry.md.
	SentryDSN                string  `koanf:"sentry_dsn"`
	SentryEnvironment        string  `koanf:"sentry_environment"`
	SentryRelease            string  `koanf:"sentry_release"`
	SentryServerName         string  `koanf:"sentry_server_name"`
	SentryDebug              bool    `koanf:"sentry_debug"`
	SentrySampleRate         float64 `koanf:"sentry_sample_rate"`
	SentryTracesSampleRate   float64 `koanf:"sentry_traces_sample_rate"`
	SentrySendDefaultPII     bool    `koanf:"sentry_send_default_pii"`
	SentryIgnoreErrors       string  `koanf:"sentry_ignore_errors"`
	SentryIgnoreTransactions string  `koanf:"sentry_ignore_transactions"`
	SentryMaxBreadcrumbs     int     `koanf:"sentry_max_breadcrumbs"`
	SentryBreadcrumbLevel    string  `koanf:"sentry_breadcrumb_level"`
	SentryMinStatus          int     `koanf:"sentry_min_status"`
	SentryCaptureRetries     bool    `koanf:"sentry_capture_retries"`
	SentryEnableTracing      bool    `koanf:"sentry_enable_tracing"`
	SentryEnableCrons        bool    `koanf:"sentry_enable_crons"`
	SentryEnableLogs         bool    `koanf:"sentry_enable_logs"`
	SentryLogLevel           string  `koanf:"sentry_log_level"`
	SentryEnableMetrics      bool    `koanf:"sentry_enable_metrics"`
	SentryMaxBodyBytes       int     `koanf:"sentry_max_body_bytes"`
	SentryFlushTimeout       int     `koanf:"sentry_flush_timeout"`

	JWTSecret string `koanf:"jwt_secret"`

	DBDriver           string `koanf:"db_driver"`
	DBConnectionString string `koanf:"db_connection_string"`
	DBHost             string `koanf:"db_host"`
	DBName             string `koanf:"db_name"`
	DBSid              string `koanf:"db_sid"`
	DBUser             string `koanf:"db_user"`
	DBPassword         string `koanf:"db_password"`
	DBPort             string `koanf:"db_port"`
	DBSSLMode          string `koanf:"db_sslmode"`
	// DBLogLevel overrides how much SQL is logged, independently of LOG_LEVEL:
	// "silent" (nothing at all), "error", "warn" (slow queries and failures —
	// the default), "info" (every statement).
	DBLogLevel string `koanf:"db_log_level"`

	// Mongo. DB_MONGO_NAME is always required — it names the database, which is
	// not taken from the connection string. DB_MONGO_HOST may be a
	// comma-separated list for a replica set.
	DBMongoHost             string `koanf:"db_mongo_host"`
	DBMongoName             string `koanf:"db_mongo_name"`
	DBMongoUserName         string `koanf:"db_mongo_username"`
	DBMongoPassword         string `koanf:"db_mongo_password"`
	DBMongoPort             string `koanf:"db_mongo_port"`
	DBMongoReplicaName      string `koanf:"db_mongo_replica_name"`
	DBMongoTLS              bool   `koanf:"db_mongo_tls"`
	DBMongoConnectionString string `koanf:"db_mongo_connection_string"`
	DBMongoMaxPoolSize      int    `koanf:"db_mongo_max_pool_size"`
	DBMongoMinPoolSize      int    `koanf:"db_mongo_min_pool_size"`
	// DBMongoTimeout is the driver's deadline for one operation, in seconds. It
	// is what stops a query started from a context with no deadline — a cron
	// run, a consumer — from hanging forever.
	DBMongoTimeout int `koanf:"db_mongo_timeout"`
	// DBMongoLogLevel overrides how much of the traffic to Mongo is logged,
	// independently of LOG_LEVEL: "silent" (nothing at all), "error", "warn"
	// (slow commands and failures — the default), "info"/"debug" (every command).
	// It is the Mongo counterpart of DB_LOG_LEVEL.
	DBMongoLogLevel string `koanf:"db_mongo_log_level"`

	MQHost             string `koanf:"mq_host"`
	MQUser             string `koanf:"mq_user"`
	MQPassword         string `koanf:"mq_password"`
	MQPort             string `koanf:"mq_port"`
	MQConnectionString string `koanf:"mq_connection_string"`

	// Cache (redis). One of CACHE_CONNECTION_STRING, CACHE_ADDRS or
	// CACHE_HOST/CACHE_PORT is enough; the rest tunes the pool. CACHE_MASTER_NAME
	// turns the address list into a sentinel list, several CACHE_ADDRS into a
	// cluster — the deployment shape is configuration, not code.
	CacheHost             string `koanf:"cache_host"`
	CachePort             string `koanf:"cache_port"`
	CacheUsername         string `koanf:"cache_username"`
	CachePassword         string `koanf:"cache_password"`
	CacheDB               int    `koanf:"cache_db"`
	CacheConnectionString string `koanf:"cache_connection_string"`
	// CacheAddrs is a comma-separated host:port list (cluster, or sentinels
	// together with CacheMasterName).
	CacheAddrs            string `koanf:"cache_addrs"`
	CacheMasterName       string `koanf:"cache_master_name"`
	CacheSentinelPassword string `koanf:"cache_sentinel_password"`
	// CachePrefix namespaces every key and channel. Set it per service (and per
	// environment) when instances share a redis, so a staging deploy cannot read
	// — or invalidate — production's keys.
	CachePrefix        string `koanf:"cache_prefix"`
	CacheTLS           bool   `koanf:"cache_tls"`
	CacheTLSSkipVerify bool   `koanf:"cache_tls_skip_verify"`
	CachePoolSize      int    `koanf:"cache_pool_size"`
	CacheMinIdleConns  int    `koanf:"cache_min_idle_conns"`
	// The three timeouts are in seconds; 0 keeps the driver's defaults (5s dial,
	// 3s read/write). CacheMaxRetries is -1 to disable retrying.
	CacheDialTimeout  int `koanf:"cache_dial_timeout"`
	CacheReadTimeout  int `koanf:"cache_read_timeout"`
	CacheWriteTimeout int `koanf:"cache_write_timeout"`
	CacheMaxRetries   int `koanf:"cache_max_retries"`

	// Object storage. S3_BUCKET is the only required key: with no access
	// key/secret pair the AWS default credential chain is used, so a deployment
	// with an instance role sets neither.
	S3Endpoint  string `koanf:"s3_endpoint"`
	S3AccessKey string `koanf:"s3_access_key"`
	S3SecretKey string `koanf:"s3_secret_key"`
	S3Bucket    string `koanf:"s3_bucket"`
	S3Region    string `koanf:"s3_region"`
	// S3IsHTTPS picks the scheme when S3_ENDPOINT was written without one
	// ("minio:9000"), as it usually is in a compose file.
	S3IsHTTPS        bool `koanf:"s3_https"`
	S3ForcePathStyle bool `koanf:"s3_force_path_style"`
	// S3Prefix namespaces every key — set it per service (and per environment)
	// when several share a bucket.
	S3Prefix string `koanf:"s3_prefix"`
	// S3PublicURL is the base address PublicURL builds on: a CDN in front of the
	// bucket, rather than the bucket itself.
	S3PublicURL string `koanf:"s3_public_url"`

	// Mail. EMAIL_SERVER is the only required key; with no username the mailer
	// authenticates with nothing, which is what an internal relay expects.
	EmailServer   string `koanf:"email_server"`
	EmailPort     int    `koanf:"email_port"`
	EmailUsername string `koanf:"email_username"`
	EmailPassword string `koanf:"email_password"`
	EmailSender   string `koanf:"email_sender"`
	// EmailSenderName is the display name every message is sent under, unless a
	// message sets its own.
	EmailSenderName string `koanf:"email_sender_name"`
	// EmailTLSPolicy is "mandatory" (the default), "opportunistic" or "none".
	// Credentials travel on this connection, so the default refuses to send at
	// all over a link the server will not encrypt.
	EmailTLSPolicy string `koanf:"email_tls_policy"`
	// EmailSSL is implicit TLS — the whole connection, from the first byte. That
	// is port 465; port 587 uses STARTTLS, which is the TLS policy above.
	EmailSSL bool `koanf:"email_ssl"`
	// EmailTLSSkipVerify accepts a certificate that does not verify. Only for a
	// self-signed relay inside a private network.
	EmailTLSSkipVerify bool `koanf:"email_tls_skip_verify"`
	// EmailAuth is "plain", "login", "cram-md5", "xoauth2", "scram-sha-1",
	// "scram-sha-256", "none", or "auto" (the default: plain when a username is
	// set, none when it is not).
	EmailAuth string `koanf:"email_auth"`
	// EmailTimeout bounds one delivery, in seconds (default 30).
	EmailTimeout int `koanf:"email_timeout"`

	FirebaseCredential string `koanf:"firebase_credential"`

	// Chat. CHAT_SLACK_TOKEN is a bot token (xoxb-…); with none the Slack
	// provider is disabled and every post fails with CHAT_DISABLED, which is
	// deliberate — an alert nobody received is worse than a service that says it
	// cannot send one.
	ChatSlackToken string `koanf:"chat_slack_token"`
	// ChatSlackChannel is where a message with no destination of its own goes —
	// "#alerts", or a channel id. A service that only ever posts to one place
	// sets it and never fills in ChatMessage.To.
	ChatSlackChannel string `koanf:"chat_slack_channel"`
	// ChatSlackTimeout bounds one post, in seconds (default 10).
	ChatSlackTimeout int `koanf:"chat_slack_timeout"`

	// Language model. AI_PROVIDER and AI_MODEL are the two that matter: with
	// either missing the model is disabled and every generation fails with
	// LLM_DISABLED, which is deliberate — an empty answer nobody noticed is
	// worse than a service that says it has no model.
	AIProvider string `koanf:"ai_provider"`
	AIModel    string `koanf:"ai_model"`
	AIAPIKey   string `koanf:"ai_api_key"`
	// AIBaseURL points a provider at another endpoint — a gateway, a proxy, or
	// any OpenAI-compatible service. Empty uses the provider's own.
	AIBaseURL string `koanf:"ai_base_url"`
	// AIMaxTokens caps a reply when the request does not (default 4096).
	AIMaxTokens int `koanf:"ai_max_tokens"`
	// AITimeout bounds one generation, in seconds (default 120). Generations
	// run far longer than an ordinary HTTP call — a reasoning model on a hard
	// prompt takes minutes — so the requester's timeout would cut them off.
	AITimeout int `koanf:"ai_timeout"`
	// AIMaxRetries is how many times a retryable failure (429, 5xx, network) is
	// retried (default 2).
	AIMaxRetries int `koanf:"ai_max_retries"`
	// AIEmbedModel is the embedding model. It is a separate key from AIModel
	// because embedding is a different model — and frequently a different
	// vendor, since the provider a service generates with may not offer
	// embeddings at all.
	AIEmbedModel string `koanf:"ai_embed_model"`
	// AIEmbedProvider overrides AI_PROVIDER for embeddings only. Empty reuses
	// it, which is right until the generation provider has no embedding API.
	AIEmbedProvider string `koanf:"ai_embed_provider"`
	// AIEmbedAPIKey and AIEmbedBaseURL likewise default to the generation ones.
	AIEmbedAPIKey  string `koanf:"ai_embed_api_key"`
	AIEmbedBaseURL string `koanf:"ai_embed_base_url"`
	// AIEmbedDimensions is the vector length to ask the model for. 0 takes the
	// model's own default, which is only right when the vector column was
	// declared with that number.
	//
	// It is configuration rather than a per-call argument because it belongs to
	// the index: gemini-embedding-001 returns 3072 unless asked otherwise, and a
	// single call that forgot to ask writes rows a vector(768) column rejects —
	// or, worse, vectors the rest of the corpus cannot be compared against.
	AIEmbedDimensions int `koanf:"ai_embed_dimensions"`

	// AILogLevel overrides how much of the model traffic is logged,
	// independently of LOG_LEVEL: "silent" (nothing), "error", "warn" (slow
	// calls and failures — the default), "info"/"debug" (every call). It is the
	// model counterpart of DB_LOG_LEVEL and HTTP_LOG_LEVEL.
	AILogLevel string `koanf:"ai_log_level"`
	// AILogPrompt writes the system prompt, the messages and the arguments the
	// model passed to a tool into those lines — everything going *to* the model.
	//
	// Off by default and meant for a development machine: a prompt carries
	// whatever the user typed, and a log store is the easiest place for that to
	// end up somewhere nobody meant it to be. Same reasoning as HTTP_LOG_BODY.
	AILogPrompt bool `koanf:"ai_log_prompt"`
	// AILogCompletion writes what came *back*: the model's reply, and what each
	// tool returned to it.
	//
	// It is a separate key from AI_LOG_PROMPT rather than the same one because
	// the two expose different things. The prompt is what the user typed; the
	// completion is what the model said and what a tool read out of the
	// database to tell it — so a service may reasonably want one and not the
	// other, and turning on prompt logging must not start writing query results
	// nobody asked for.
	//
	// Off by default, for the same reason.
	AILogCompletion bool `koanf:"ai_log_completion"`
	// AILogSlow is when a generation is slow enough to warn about, in seconds
	// (default 30). Tens of seconds rather than the hundreds of milliseconds an
	// HTTP call is judged by, because a reasoning model genuinely takes that
	// long — warning sooner would mark every normal call as slow.
	AILogSlow int `koanf:"ai_log_slow"`
}

ENVConfig is the strongly-typed configuration. Field names/keys mirror v1; adding a key means adding a field here only — the loader binds env vars by prefix automatically (v1 needed a second manual envKeys list).

type EmailAddress

type EmailAddress struct {
	Name    string
	Address string
}

EmailAddress is a recipient with a display name.

func (EmailAddress) String

func (a EmailAddress) String() string

String renders the address in the form a header takes, quoting the name when it needs quoting.

type EmailMessage

type EmailMessage struct {
	// From overrides EMAIL_SENDER for this message; FromName the display name.
	From     string
	FromName string

	To  []string
	Cc  []string
	Bcc []string
	// ToAddresses and its siblings are the named form of the three lists above.
	// Both may be used; they are concatenated.
	ToAddresses  []EmailAddress
	CcAddresses  []EmailAddress
	BccAddresses []EmailAddress

	ReplyTo string
	Subject string

	// HTML and Text are the bodies. Send both when you can: HTML for the client
	// that renders it, text for the one that does not — and for the spam filter,
	// which treats an HTML-only message as a small strike against it.
	HTML string
	Text string

	// Attachments are sent as files; Embeds are inline parts the HTML body
	// references by content id.
	Attachments []Attachment
	Embeds      []Attachment

	// Headers are extra headers (List-Unsubscribe, X-Entity-Ref-ID, ...).
	Headers map[string]string

	Priority EmailPriority
}

EmailMessage describes an outbound email.

func SentMail

func SentMail(m IMailer) []EmailMessage

SentMail returns what a memory mailer has recorded, in order. It returns nil for any other mailer.

type EmailPriority

type EmailPriority uint8

EmailPriority maps to the Importance/Priority headers a mail client shows.

const (
	PriorityNormal EmailPriority = iota
	PriorityLow
	PriorityHigh
)

type EmbedRequest

type EmbedRequest struct {
	// Texts is what to embed, one vector out per text, in order. Must not be
	// empty.
	Texts []string
	// Model overrides the configured embedding model. It is the provider's own
	// model id.
	Model string
	// Dimensions is the vector length to ask for. 0 uses the model's default,
	// which is the right choice unless a column says otherwise.
	//
	// It matters because the default is frequently not what a schema was built
	// for: gemini-embedding-001 returns 3072 unless asked for less, so a
	// vector(768) column rejects every row — or, with a driver that truncated
	// instead, accepts vectors that no longer match the corpus.
	Dimensions int
	// Task is what the vectors are for. See EmbedTask.
	Task EmbedTask
	// ProviderOptions carries provider-specific parameters straight through,
	// untranslated, merged over whatever Dimensions and Task produced. Same
	// escape hatch as LLMRequest.ProviderOptions, and the same trade-off: no
	// compile-time checking, so prefer a typed field when one exists.
	ProviderOptions map[string]any
}

EmbedRequest is one embedding call with the options Embed cannot express.

Everything beyond Texts is optional, and a driver that cannot honour a field it was given returns ErrEmbedUnsupported rather than sending the request without it — a vector of the wrong length or built for the wrong task is not a degraded result, it is a wrong one that nothing downstream can detect.

func EmbeddedRequests

func EmbeddedRequests(e IEmbedder) []EmbedRequest

EmbeddedRequests returns the calls a memory embedder recorded, in order — the counterpart of core.LLMCalls, and the way a test asserts that the corpus was indexed as documents and the search embedded as a query. It returns nil for any other embedder.

func (EmbedRequest) Validate

func (r EmbedRequest) Validate() IError

Validate checks the request the way every driver must, before anything is sent. Exported for the same reason LLMRequest.Validate is: drivers live in other packages and a caller's mistake has to read identically whichever provider is configured.

type EmbedTask

type EmbedTask string

EmbedTask is what the vectors are going to be used for.

It is not a stylistic hint. A model that supports task types embeds the same sentence into a different vector depending on the answer, and a corpus indexed as documents but searched with query vectors built as documents retrieves measurably worse — silently, because every number involved still looks like a perfectly good similarity score.

Providers spell these differently (Google RETRIEVAL_DOCUMENT, Cohere/Voyage input_type) and some have no concept of them at all, so a driver that cannot honour one returns ErrEmbedUnsupported rather than dropping it.

const (
	// EmbedTaskDefault leaves the provider's own default in place. It is the
	// zero value, so an EmbedRequest that says nothing behaves exactly like the
	// plain Embed it replaced.
	EmbedTaskDefault EmbedTask = ""
	// EmbedDocument is for the corpus side of a search — the text being indexed.
	EmbedDocument EmbedTask = "document"
	// EmbedQuery is for the search side. Pair it with EmbedDocument: using one
	// without the other is the mistake this type exists to prevent.
	EmbedQuery EmbedTask = "query"
	// EmbedSimilarity is for comparing two texts symmetrically — deduplication,
	// near-duplicate detection — where neither side is a query.
	EmbedSimilarity     EmbedTask = "similarity"
	EmbedClassification EmbedTask = "classification"
	EmbedClustering     EmbedTask = "clustering"
)

type Error

type Error struct {
	Status  int         `json:"-"`
	Code    string      `json:"code"`
	Message interface{} `json:"message"`
	Data    interface{} `json:"-"`
	Fields  interface{} `json:"fields,omitempty"`
	// contains filtered or unexported fields
}

Error is the concrete IError. Exported fields mirror v1 so existing response shapes are unchanged; cause and stack are captured for diagnostics.

func ErrJobRunNotFound

func ErrJobRunNotFound(id string) *Error

ErrJobRunNotFound is returned when a run id does not exist.

func From

func From(err error) *Error

From converts any error to an *Error using errors.As (never panics). Errors that are not already *Error become a 500. Returns nil for a nil error.

func InternalServerError

func InternalServerError() *Error

InternalServerError is the fallback 500 used when no error type is supplied.

func New

func New(status int, code string, message string) *Error

New builds an *Error with the given status, code and message, capturing the call site for the stack trace.

func Newf

func Newf(status int, code string, format string, args ...interface{}) *Error

Newf is New with a formatted message. It builds the error itself instead of delegating to New so the captured stack starts at the caller, not at Newf.

func Wrap

func Wrap(err error, message string) *Error

Wrap turns any error into an *Error (500 by default) without ever panicking. If err already is (or wraps) an *Error, that error is returned enriched with the extra message so the original status/code/fields are preserved.

func Wrapf

func Wrapf(err error, format string, args ...interface{}) *Error

Wrapf is Wrap with a formatted message.

func (*Error) Error

func (e *Error) Error() string

func (*Error) EventID

func (e *Error) EventID() string

EventID is the Sentry event this error was reported as, or "" when it was never reported (no DSN, or a status below the reporting threshold). Handing it to a user turns "it broke" into a one-click lookup.

func (*Error) GetCode

func (e *Error) GetCode() string

func (*Error) GetMessage

func (e *Error) GetMessage() interface{}

func (*Error) GetStatus

func (e *Error) GetStatus() int

func (*Error) Is

func (e *Error) Is(target error) bool

Is reports whether target is an *Error with the same code, so sentinels can be matched with errors.Is regardless of wrapping.

func (*Error) JSON

func (e *Error) JSON() interface{}

func (*Error) OriginalError

func (e *Error) OriginalError() error

OriginalError returns the wrapped cause, or the error itself when there is none (matching v1 semantics).

func (*Error) StackString

func (e *Error) StackString() string

StackString renders the captured call stack as "func\n\tfile:line" frames.

func (*Error) StackTrace

func (e *Error) StackTrace() []uintptr

StackTrace returns the program counters captured when the error was created. sentry-go looks for this method by reflection, so a reported error carries the stack of where it actually happened — not of where it was captured.

func (*Error) Unwrap

func (e *Error) Unwrap() error

func (*Error) WithCause

func (e *Error) WithCause(cause error) *Error

WithCause returns a copy wrapping cause (for errors.Is / errors.As chains).

func (*Error) WithCode

func (e *Error) WithCode(code string) *Error

WithCode returns a copy with a different code.

func (*Error) WithData

func (e *Error) WithData(data interface{}) *Error

WithData returns a copy carrying non-serialised data.

func (*Error) WithFields

func (e *Error) WithFields(fields interface{}) *Error

WithFields returns a copy carrying validation/detail fields.

func (*Error) WithMessage

func (e *Error) WithMessage(message interface{}) *Error

WithMessage returns a copy with a different message.

func (*Error) WithStatus

func (e *Error) WithStatus(status int) *Error

WithStatus returns a copy with a different HTTP status.

type ExchangeConfig

type ExchangeConfig struct {
	Name string
	// Kind is direct, fanout, topic or headers (default direct).
	Kind string
	// Durable survives a broker restart. On by default — the zero value here is
	// durable, because a non-durable exchange is almost never what is wanted.
	Transient  bool
	AutoDelete bool
	Internal   bool
	Args       map[string]any
}

ExchangeConfig declares an exchange.

type Group

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

Group is a route group that likewise remembers the App.

func (*Group) App

func (g *Group) App() *App

App returns the App the group belongs to, as Server.App does.

func (*Group) DELETE

func (g *Group) DELETE(path string, h HandlerFunc, m ...echo.MiddlewareFunc) echo.RouteInfo

func (*Group) Echo

func (g *Group) Echo() *echo.Group

Echo returns the underlying echo group (escape hatch).

func (*Group) GET

func (g *Group) GET(path string, h HandlerFunc, m ...echo.MiddlewareFunc) echo.RouteInfo

func (*Group) Group

func (g *Group) Group(prefix string, m ...echo.MiddlewareFunc) *Group

Group creates a nested group.

func (*Group) PATCH

func (g *Group) PATCH(path string, h HandlerFunc, m ...echo.MiddlewareFunc) echo.RouteInfo

func (*Group) POST

func (g *Group) POST(path string, h HandlerFunc, m ...echo.MiddlewareFunc) echo.RouteInfo

func (*Group) PUT

func (g *Group) PUT(path string, h HandlerFunc, m ...echo.MiddlewareFunc) echo.RouteInfo

func (*Group) Use

func (g *Group) Use(m ...echo.MiddlewareFunc)

Use adds middleware to the group.

type HTTPOptions

type HTTPOptions struct {
	AllowOrigins []string
	AllowHeaders []string
	// DisableRequestLog turns off the per-request access line — for a service
	// behind a gateway that already logs every request, or one whose traffic is
	// health checks. Nil follows LOG_REQUEST (on by default); set it to override
	// the environment either way.
	//
	// Nothing else is affected: breadcrumbs, Sentry Logs, error reporting and
	// tracing are their own switches.
	DisableRequestLog *bool

	// BodyLimit caps how large a request body may be, in bytes. Zero takes
	// DefaultBodyLimit; a negative value turns the cap off entirely.
	//
	// Raise it on the routes that accept uploads rather than for the whole
	// server — the limit is ordinary middleware, so a group can carry its own:
	//
	//	files := e.Group("/files", core.BodyLimit(100<<20))
	BodyLimit int64

	// The four http.Server deadlines. Zero takes the framework default (see the
	// Default* constants); a negative value turns that deadline off.
	//
	// A BeforeServeFunc of your own still runs after these and wins, for the
	// settings this does not name.
	ReadTimeout       time.Duration
	ReadHeaderTimeout time.Duration
	WriteTimeout      time.Duration
	IdleTimeout       time.Duration
}

HTTPOptions configures the HTTP server.

type HandlerFunc

type HandlerFunc func(c IHTTPContext) error

HandlerFunc is an mine-core HTTP handler.

func LiveHandler

func LiveHandler() HandlerFunc

LiveHandler answers 200 as long as the process is running. It touches no dependency on purpose.

This is the liveness probe, and the only correct answer to "is this process wedged?" is one that cannot fail for any other reason. A liveness probe that pings the database restarts every instance of the service when the database hiccups, turning one outage into two.

func ReadyHandler

func ReadyHandler(app *App, opts ...HealthOptions) HandlerFunc

ReadyHandler answers whether this instance can serve traffic: it probes every dependency the App holds, in parallel, and reports each one.

e.GET("/healthz", core.LiveHandler())
e.GET("/readyz", core.ReadyHandler(app))

A critical dependency being down answers 503, which is what takes the instance out of the load balancer without restarting it.

type HealthCheck

type HealthCheck struct {
	// Name is what the result is keyed by in the body ("database", "cache").
	Name string
	// Check reports whether the dependency is usable. It must respect ctx.
	Check func(ctx context.Context) error
	// Critical decides what a failure means. A critical dependency failing makes
	// the service not ready (503); a non-critical one makes it degraded (200).
	//
	// Ask "can this instance still do its job without it?" A cache usually yes,
	// the primary database usually no.
	Critical bool
}

HealthCheck is one dependency the readiness probe asks about.

func AppHealthChecks

func AppHealthChecks(app *App) []HealthCheck

AppHealthChecks is what the App can probe on its own: every registered SQL and Mongo connection, every cache, the queue and object storage.

Only configured dependencies appear. A service with no redis has no cache check, rather than a cache check that always fails — the probe reports what this deployment actually depends on.

The database connections are critical and the rest are not, which is the common case rather than a rule; replace the list with HealthOptions.Only when it is wrong for a service.

type HealthOptions

type HealthOptions struct {
	// Timeout bounds the whole probe (default DefaultHealthTimeout). A check
	// that has not answered by then is reported as down.
	Timeout time.Duration
	// Details includes each dependency's error text in the body. Nil follows the
	// environment: on outside production, off in it — an error string can name a
	// host, a user or a bucket, and a probe endpoint is often the one route
	// nobody remembers to put behind the gateway.
	Details *bool
	// Checks are extra dependencies to probe, alongside the ones the App knows
	// about. Use them for things the framework cannot see: a partner API, a
	// license server, a mounted volume.
	Checks []HealthCheck
	// Only replaces the App's own checks entirely, rather than adding to them.
	// For a service that wants to name exactly what it probes.
	Only []HealthCheck
}

HealthOptions tunes the readiness probe.

type HealthReport

type HealthReport struct {
	Status  string                 `json:"status"`
	Service string                 `json:"service,omitempty"`
	Checks  map[string]CheckResult `json:"checks,omitempty"`
	TookMS  int64                  `json:"took_ms"`
}

HealthReport is the body of a readiness probe.

func CheckHealth

func CheckHealth(ctx context.Context, app *App, opts ...HealthOptions) HealthReport

CheckHealth runs the probe and returns the report, for a caller that wants to answer in its own shape — a startup gate, a CLI, a different route.

type ICache

type ICache interface {

	// Get reads key into dest. dest may be *string, *[]byte or *json.RawMessage
	// for the raw bytes; anything else is JSON-decoded. The error wraps
	// ErrCacheMiss when the key is absent.
	Get(key string, dest any) IError
	// Set stores value under key. string/[]byte are stored as-is, everything
	// else is JSON-encoded. ttl of NoExpiry stores it forever, KeepTTL keeps the
	// key's current expiry.
	Set(key string, value any, ttl time.Duration) IError
	// SetNX stores value only when key does not exist, and reports whether it
	// did. This is the primitive behind idempotency keys and one-shot flags.
	SetNX(key string, value any, ttl time.Duration) (bool, IError)
	// GetDel reads key into dest and deletes it in the same round trip — for
	// one-time values (OTPs, single-use tokens) that must not be replayed.
	GetDel(key string, dest any) IError
	// MGet reads many keys at once. Absent keys are simply missing from the
	// result, which is therefore empty rather than an error when none exist.
	MGet(keys ...string) (map[string][]byte, IError)
	// MSet writes many keys with one ttl in a single pipeline.
	MSet(values map[string]any, ttl time.Duration) IError
	// Del removes keys. Absent keys are not an error.
	Del(keys ...string) IError
	// DelByPrefix removes every key under a prefix and returns how many it
	// deleted. It scans in batches instead of running KEYS, so it is safe to
	// call against a production instance.
	DelByPrefix(prefix string) (int64, IError)
	// Exists reports whether key is present.
	Exists(key string) (bool, IError)
	// Expire sets a key's ttl and reports whether the key existed.
	Expire(key string, ttl time.Duration) (bool, IError)
	// TTL returns a key's remaining life, TTLNoExpiry when it has none, and an
	// ErrCacheMiss error when the key is absent.
	TTL(key string) (time.Duration, IError)

	// Incr adds delta to a counter and returns the new value; a negative delta
	// subtracts and a delta of 0 reads it (creating it at zero). When the
	// counter is created by this call and ttl is positive, the ttl is applied to
	// it — so a fixed-window rate limiter is one call, not three.
	Incr(key string, delta int64, ttl time.Duration) (int64, IError)

	// Lock acquires a mutual-exclusion lock held for at most ttl. It tries once;
	// the returned error wraps ErrLockNotAcquired when somebody else holds it.
	// Use LockWait to wait for a turn.
	Lock(key string, ttl time.Duration) (ILock, IError)

	// PubSub is the publish/subscribe side of the same connection. Never nil.
	PubSub() IPubSub

	// Ping checks the connection is usable — for a readiness probe.
	Ping() IError
	// Enabled reports whether this is a real cache. False for the disabled cache
	// a service with no CACHE_* configuration gets.
	Enabled() bool
	// Prefix is the string every key of this handle is stored under.
	Prefix() string
	// WithPrefix returns a handle that namespaces keys further, e.g.
	// ctx.Cache().WithPrefix("otp") writes "otp:<key>". A ":" is appended when
	// the prefix does not already end in one.
	WithPrefix(prefix string) ICache
	// WithContext returns a handle bound to a different context (escape hatch
	// for work that must outlive the request).
	WithContext(ctx context.Context) ICache
	// Redis exposes the underlying client for anything this interface does not
	// cover. It is nil for the memory and disabled caches, and it does not apply
	// the prefix — build keys with Prefix() when you use it.
	Redis() redis.UniversalClient
	// Close releases the connection. Owned by App.Shutdown; call it yourself
	// only for a cache you built outside an App.
	Close() IError
}

ICache is the cache abstraction. Same name as v1; methods no longer take a ctx because ctx.Cache() returns a handle already bound to the request context.

ctx.Cache() is never nil: a service with no CACHE_* configuration gets a disabled cache whose reads miss and whose writes are dropped, so cache-aside code (Remember) runs unchanged in an environment that has no redis. Check Enabled when a code path genuinely needs one.

func NewCacheWithClient

func NewCacheWithClient(rdb redis.UniversalClient, opts ...CacheOption) ICache

NewCacheWithClient wraps an existing redis client (useful for tests, or for a client built with options this package does not expose).

func NewMemoryCache

func NewMemoryCache() ICache

NewMemoryCache returns an in-process cache. Wire it like any other:

app, _ := core.NewApp(env, core.WithCache("default", core.NewMemoryCache()))

Close stops its expiry sweeper; an App does that for you.

func NewNoopCache

func NewNoopCache() ICache

NewNoopCache returns a cache that stores nothing. It is what a service with no CACHE_* configuration gets, so the call path is identical in every environment.

type IChat

type IChat interface {
	// Send posts one message, bounded by the handle's context.
	Send(msg ChatMessage) (ChatResult, IError)
	// Ping checks the credentials without posting anything, for a readiness
	// probe. A provider with no way to ask returns nil.
	Ping() IError
	// Enabled reports whether this is a real provider.
	Enabled() bool
	// Provider names the platform ("slack"), for a capability listing.
	Provider() string
	// WithContext returns a handle bound to a different context.
	WithContext(ctx context.Context) IChat
	// Close releases whatever the provider holds. Owned by App.Shutdown.
	Close() IError
}

IChat posts messages to a chat platform — Slack, Discord, LINE.

core.Chat(ctx) is never nil: a service with no chat configuration gets a disabled provider whose every call fails with CHAT_DISABLED.

func Chat

func Chat(ctx context.Context) IChat

Chat returns the application's default chat provider bound to ctx.

It is a function rather than a method on IContext, for the same reason core.Mailer and core.Requester are: posting a message is not a capability of the request — it is something code does, with the request's deadline and trace attached. Taking only a context.Context is what lets a service that knows nothing about this framework post one:

func (s *DeployService) Announce(ctx context.Context, d Deploy) error {
    _, err := core.Chat(ctx).Send(core.ChatMessage{
        Title: "Deploy finished", Level: core.ChatSuccess,
        Fields: []core.ChatField{{Name: "version", Value: d.Version}},
    })
    return err
}

A context from nowhere — context.Background() in a script or an early test — gets the disabled provider rather than nil, so a call site never has to nil-check. Every call on it fails with CHAT_DISABLED.

func Chats

func Chats(ctx context.Context, name string) IChat

Chats returns a named chat provider bound to ctx.

Providers are named the way SQL connections and caches are, rather than there being one of them, because one service routinely posts to more than one place: alerts to an internal Slack, replies to customers on LINE. An unregistered name gives the disabled provider rather than nil.

func NewMemoryChat

func NewMemoryChat() IChat

NewMemoryChat returns a provider that records messages instead of posting them, so a test can assert on what a service would have said:

c := core.NewMemoryChat()
app, _ := core.NewApp(env, core.WithChat("default", c))
...
sent := core.SentChatMessages(c)
require.Len(t, sent, 1)
assert.Equal(t, core.ChatError, sent[0].Level)

It runs the same validation a real provider does, so a message the platform would have rejected fails the test rather than passing it.

func NewNoopChat

func NewNoopChat() IChat

NewNoopChat returns a provider that refuses every operation. It is what a service with no chat configuration gets, so the failure is a clear error instead of a nil dereference.

type IContext

type IContext interface {
	context.Context

	ENV() IENV
	Log() ILogger
	Mode() Mode
	// Sentry returns the error tracker bound to this request/run: captures made
	// through it carry this context's user, tags and breadcrumbs. It is never
	// nil — with no DSN configured every call is a no-op.
	Sentry() ISentry
	// Meter records measurements on this request/run's trace. Never nil — with
	// metrics off every call is a no-op.
	Meter() IMeter

	DB() *gorm.DB
	DBS(name string) *gorm.DB
	DBMongo() IMongoDB
	DBSMongo(name string) IMongoDB
	// Cache returns the default cache, bound to this request/run. It is never
	// nil — with no cache configured every read misses and every write is
	// dropped, so cache-aside code runs unchanged. Check Enabled when a path
	// genuinely needs one.
	Cache() ICache
	Caches(name string) ICache
	// PubSub is the publish/subscribe side of the default cache. Never nil.
	PubSub() IPubSub
	MQ() IMQ
	// Storage is object storage, bound to this request/run. Never nil — with no
	// bucket configured every call fails with STORAGE_DISABLED rather than
	// panicking. Unlike the cache it does not degrade quietly: an upload that
	// was silently dropped is a file nobody can get back.
	Storage() IStorage

	NewError(err error, errorType IError, args ...interface{}) IError

	GetUser() *ContextUser
	SetUser(user *ContextUser)
	GetData(name string) interface{}
	GetAllData() map[string]interface{}
	SetData(name string, data interface{})

	// WithContext returns a shallow copy bound to a different underlying context
	// (escape hatch for background timeouts). Rarely needed.
	WithContext(ctx context.Context) IContext
}

IContext is the per-request/per-job container. It embeds context.Context so it is the single ambient context: capability accessors return handles already bound to it, so callers never pass a ctx explicitly. Method names match v1.

func Set

func Set[T any](ctx IContext, key string, value T) IContext

Set stores a typed value on the context's data bag and returns ctx for chaining.

type ICronModule

type ICronModule interface {
	Cron(sc *Scheduler) IError
}

ICronModule arms the module's scheduled jobs. Only a role with a Scheduler (worker, all) gets this far.

Scheduler.Add both registers and arms, so a job armed here must not also be registered in Jobs — that is a duplicate name, and it is reported as one.

type ICronjobContext

type ICronjobContext interface {
	IContext

	// JobName is the name the job was registered under.
	JobName() string
	// RunID identifies this single execution.
	RunID() string
	// Attempt is 1-based; attempt 2 is the first automatic retry.
	Attempt() int
	// Trigger reports what caused this run (schedule, manual, retry, replay…).
	Trigger() Trigger

	// Params decodes the run parameters into dest and validates them when dest
	// implements IValidateContext (preferred) or IValidate. Missing params leave
	// dest at its zero value.
	//
	// The run context *is* an IContext, so parameters validate with the same
	// builder — and the same DB-backed rules — as an HTTP request payload:
	//
	//	func (p *ReportParams) Valid(ctx core.IContext) core.IError {
	//	    v := valid.New(ctx)
	//	    v.Str("date", p.Date).Required().Date()
	//	    v.Str("code", p.Code).Exists("coupons", "code")
	//	    return v.Error()
	//	}
	//
	// Violations fail the run before the handler is called, and are stored on
	// JobRun.Error.Fields.
	Params(dest any) IError

	// Progress reports how far the run has got (0-100), visible to whoever is
	// watching the run.
	Progress(percent int, message string)
	// SetResult stores a summary of what the run produced.
	SetResult(v any)

	// Stopping is closed when the run has been asked to stop (cancel, timeout,
	// or shutdown). Long loops must check it — Go cannot kill a goroutine, so
	// cancellation is always cooperative.
	//
	//	for _, item := range items {
	//	    if c.IsStopping() { return c.Err() }
	//	    ...
	//	}
	Stopping() <-chan struct{}
	// IsStopping is a non-blocking Stopping() check.
	IsStopping() bool
}

ICronjobContext is the per-run context of a job. It keeps v1's name and its JobName() method, and adds everything a manually triggerable, parameterised run needs.

type IDocument

type IDocument interface {
	CollectionName() string
}

IDocument is implemented by Mongo models, the way IModel is by SQL ones. It is what lets mongorepo.New[User](ctx) know which collection to read.

func (u User) CollectionName() string { return "users" }

Declare it on the value, not the pointer, so New[User] rather than New[*User] satisfies the constraint.

type IENV

type IENV interface {
	Config() *ENVConfig
	IsDev() bool
	IsTest() bool
	IsMock() bool
	IsProd() bool
	Bool(key string) bool
	Int(key string) int
	Float64(key string) float64
	String(key string) string
	All() map[string]string
}

IENV exposes configuration. Same interface as v1 so callers do not relearn, but the implementation is a per-instance koanf (no global viper, no manual key-bind list).

type IEmbedder

type IEmbedder interface {
	// Embed returns one vector per input, in the same order. Sending a batch is
	// meaningfully cheaper than a call each — providers charge per token, not
	// per request, and the round trips dominate for short texts.
	Embed(texts ...string) ([][]float32, IError)
	// EmbedOne is Embed for a single text, which is what a search query is.
	EmbedOne(text string) ([]float32, IError)
	// EmbedWith is Embed with the options a real index needs — a vector length
	// that matches the column, a task type that matches how the vector will be
	// used, and the provider's own parameters underneath both.
	//
	//	docs, err := core.Embedder(ctx).EmbedWith(core.EmbedRequest{
	//	    Texts: chunks, Dimensions: 768, Task: core.EmbedDocument,
	//	})
	//
	// Embed is EmbedWith with an empty request, so the two share one code path
	// and a driver cannot honour options on one and ignore them on the other.
	EmbedWith(req EmbedRequest) ([][]float32, IError)
	// Dimensions is the vector length this model produces, or 0 when it is not
	// known before the first call. A vector column has to be declared with it,
	// so it is worth knowing at startup rather than at migration time.
	//
	// A configured length (AI_EMBED_DIMENSIONS) is reported straight away; other
	// models learn it from their first response. A per-request Dimensions does
	// not change it — that is a property of the call, not of the handle.
	Dimensions() int
	Model() string
	Provider() string
	Enabled() bool
	WithContext(ctx context.Context) IEmbedder
	Close() IError
}

IEmbedder turns text into vectors.

It is a separate capability from ILLM rather than a method on it because the two are separate models with separate ids, separate pricing and — often — separate vendors: Anthropic has no embedding endpoint at all, so a service using Claude for generation embeds with something else entirely.

core.Embedder(ctx) is never nil: a service with no AI_EMBED_MODEL gets a disabled embedder whose every call fails with EMBED_DISABLED.

func Embedder

func Embedder(ctx context.Context) IEmbedder

Embedder returns the application's embedding model bound to ctx.

Same shape and same reasoning as core.LLM: embedding is something you do with the request's deadline attached, not a property of the request.

func NewMemoryEmbedder

func NewMemoryEmbedder(dims ...int) IEmbedder

NewMemoryEmbedder returns an embedder that hashes text into vectors, so a test can index and search without a key, a network or a bill.

e := core.NewMemoryEmbedder(8)
app, _ := core.NewApp(env, core.WithEmbedder(e))

dims defaults to 8 — small enough to print in a failing assertion, large enough that unrelated texts do not collide.

func NewNoopEmbedder

func NewNoopEmbedder() IEmbedder

NewNoopEmbedder returns an embedder that refuses every call.

type IError

type IError interface {
	error
	// GetCode returns the machine-readable error code (stable, safe to expose).
	GetCode() string
	// GetStatus returns the HTTP status the error maps to.
	GetStatus() int
	// GetMessage returns the human-readable message (safe to expose).
	GetMessage() interface{}
	// JSON returns the value serialised in HTTP responses.
	JSON() interface{}
	// OriginalError returns the wrapped cause, or the error itself when there is none.
	OriginalError() error
	// Unwrap exposes the wrapped cause for errors.Is / errors.As.
	Unwrap() error
}

IError is the structured error returned by every mine-core layer. It keeps the v1 method set (so callers do not have to relearn) and additionally supports the standard library's errors.Is / errors.As via Unwrap.

func BindDelivery

func BindDelivery[T any](d *Delivery) (T, IError)

BindDelivery decodes a delivery's body into a T.

order, err := core.BindDelivery[Order](d)

func BindMessage

func BindMessage[T any](m *PubSubMessage) (T, IError)

BindMessage is the typed form of PubSubMessage.Bind.

func CSVEach

func CSVEach[T any](r io.Reader, fn func(T) error, opts ...CSVOptions) IError

CSVEach reads CSV from r and calls fn once per row, holding one row in memory at a time. An error from fn stops the read and is returned.

func CSVMarshal

func CSVMarshal[T any](w io.Writer, rows []T, opts ...CSVOptions) IError

CSVMarshal writes rows as CSV to w. The header is taken from each field's `csv:"name"` tag (falling back to the field name); fields tagged `csv:"-"` are skipped.

Supported field types: string, bool, the integer and float kinds, time.Time, anything implementing encoding.TextMarshaler, and pointers to those (a nil pointer writes an empty cell). A field of any other type is an error rather than an empty column — a report missing a value is worse than one that failed to build.

func CSVUnmarshal

func CSVUnmarshal[T any](r io.Reader, opts ...CSVOptions) ([]T, IError)

CSVUnmarshal reads CSV from r into a slice of T, matching columns by header against the `csv` tag / field name. A UTF-8 BOM, if present, is ignored.

It holds the whole result in memory; use CSVEach for a file whose size you do not control.

func ChatDisabledError

func ChatDisabledError() IError

ChatDisabledError is the error a disabled provider returns. Drivers use it so that a provider left unconfigured fails identically to none being registered.

func EmbedUnsupportedError

func EmbedUnsupportedError(provider, feature string) IError

EmbedUnsupportedError reports that an embedding model cannot do what the request asked for. Drivers use it so the message is identical across providers, which is what makes it worth asserting on in a test.

func GetJSON

func GetJSON[T any](c ICache, key string) (T, IError)

GetJSON reads and decodes a value into T. The error wraps ErrCacheMiss on absence.

func GetJSONMany

func GetJSONMany[T any](c ICache, keys ...string) (map[string]T, IError)

GetJSONMany reads many keys in one round trip and decodes each into T. Keys that are absent — or hold something that is not a T — are left out of the result rather than failing the batch, which is what a cache read should do.

func InstrumentGorm

func InstrumentGorm(db *gorm.DB, opts ...SentryGormOptions) IError

InstrumentGorm makes every query leave a Sentry breadcrumb, so an issue shows the statements that ran before the failure — usually the one that caused it.

It is opt-in because it touches every query:

db, _ := core.NewDatabase(env)
_ = core.InstrumentGorm(db)
app, _ := core.NewApp(env, core.WithSQL("default", db))

A query whose context carries no hub (a background task outside any request or run) records nothing, so the cost is one map lookup.

func JWTSign

func JWTSign(claims jwt.Claims, secret string) (string, IError)

JWTSign signs claims with HS256 using secret. claims is any jwt.Claims implementation (e.g. jwt.RegisteredClaims or a struct embedding it).

func JWTVerify

func JWTVerify(tokenString string, secret string, dest jwt.Claims) IError

JWTVerify parses tokenString, verifies the HMAC signature with secret and the standard time-based claims, and decodes into dest (a pointer to a jwt.Claims).

func LLMDisabledError

func LLMDisabledError() IError

LLMDisabledError is the error every disabled-model call fails with. Drivers should return it too when their own configuration turns out to be missing, so the failure reads the same wherever it came from.

func LLMUnsupportedError

func LLMUnsupportedError(provider, feature string) IError

LLMUnsupportedError reports that a model cannot do what the request asked for. Drivers use it so the message is identical across providers, which is what makes it worth asserting on in a test.

func MongoEach

func MongoEach[T any](ctx context.Context, cur *mongo.Cursor, fn func(T) error) IError

MongoEach decodes a cursor one document at a time, so a result set larger than memory can be processed. It closes the cursor.

cur, err := m.AggregateCursor("events", pipeline, core.MongoAggregateOptions{AllowDiskUse: true})
if err != nil { return err }
err = core.MongoEach(ctx, cur, func(row Row) error { return write(row) })

Returning an error from fn stops the iteration and returns it.

func MongoObjectID

func MongoObjectID(id string) (bson.ObjectID, IError)

MongoObjectID parses a hex id. A filter built with the string instead of the ObjectID matches nothing, silently, which is the single most common way to lose an afternoon with Mongo.

func NewDatabase

func NewDatabase(env IENV, opts ...DBOption) (*gorm.DB, IError)

NewDatabase opens a GORM connection from configuration. The driver is taken from DB_DRIVER, or detected from the connection string's scheme.

func PublishAs

func PublishAs[T any](mq IMQ, exchange, key string, msg T) IError

PublishAs is a typed convenience over IMQ.Publish.

func RegisterJob

func RegisterJob[P any](r *JobRegistry, def JobDef, fn func(c ICronjobContext, params P) error) IError

RegisterJob adds a job whose parameters are decoded into P and validated when P implements IValidate/IValidateContext. Scheduled runs get the zero value of P unless the trigger supplies params.

type ReportParams struct {
    Date string `json:"date"`
}

core.RegisterJob(reg, core.JobDef{Name: "report"},
    func(c core.ICronjobContext, p ReportParams) error { ... })

func Remember

func Remember[T any](c ICache, key string, ttl time.Duration, load func() (T, error)) (T, IError)

Remember returns the cached value for key, or computes it with load, caches it (best-effort) and returns it.

A cache that is down, disabled or holding a value written by an older version of the struct is not an error: load runs and the result is served. Only load failing fails the call.

func RememberOnce

func RememberOnce[T any](c ICache, key string, ttl, wait time.Duration, load func() (T, error)) (T, IError)

RememberOnce is Remember with a lock around the loader, so a key that expires under load is recomputed by one caller instead of by all of them. The others wait up to wait for the winner to publish, then fall back to loading it themselves rather than failing.

Use it when load is expensive enough that a stampede would hurt; Remember is cheaper and right for everything else.

func SetJSON

func SetJSON[T any](c ICache, key string, v T, ttl time.Duration) IError

SetJSON stores v as JSON under key.

func SignJWT

func SignJWT(secret string, claims jwt.MapClaims, ttl time.Duration) (string, IError)

SignJWT issues an HS256 token for claims valid for ttl (iat/exp set automatically; ttl<=0 means no expiry).

func ValidateChatMessage

func ValidateChatMessage(msg ChatMessage) IError

ValidateChatMessage rejects a message no provider could send.

It is exported because providers live outside this package — a driver calls it first so that a bug in a caller is reported the same way whichever platform is configured, and before a request is made rather than as somebody's API error.

func WithLock

func WithLock(c ICache, key string, ttl time.Duration, fn func() error) IError

WithLock runs fn while holding key, and releases it afterwards however fn ends — including a panic. It is the shape almost every caller wants:

err := core.WithLock(ctx.Cache(), "settle:"+id, time.Minute, func() error {
    return settle(ctx, id)
})

When somebody else holds the lock it returns an ErrLockNotAcquired error without running fn.

type IFieldSourced

type IFieldSourced interface {
	// SetFieldSources takes field path -> source ("path"/"query"/"header"/"body").
	SetFieldSources(map[string]string)
}

IFieldSourced is implemented by validation errors that can record where each field was bound from. Declared here rather than in valid/ because core cannot import valid (valid imports core); the HTTP layer only needs this behaviour, not the concrete type.

type IHTTPContext

type IHTTPContext interface {
	IContext

	// --- request ---
	Request() *http.Request
	SetRequest(r *http.Request)
	// Response is the raw writer. echo's own recorder (Status, Size, Committed)
	// is reached with echo.UnwrapResponse.
	Response() http.ResponseWriter
	IsTLS() bool
	IsWebSocket() bool
	Scheme() string
	RealIP() string

	// --- routing ---
	// Path is the registered route pattern ("/users/:id"), not the concrete URL.
	Path() string
	RouteInfo() echo.RouteInfo
	Param(name string) string
	ParamOr(name, defaultValue string) string
	PathValues() echo.PathValues
	QueryParam(name string) string
	QueryParamOr(name, defaultValue string) string
	QueryParams() url.Values
	QueryString() string

	// --- payload ---
	FormValue(name string) string
	FormValueOr(name, defaultValue string) string
	FormValues() (url.Values, error)
	FormFile(name string) (*multipart.FileHeader, error)
	MultipartForm() (*multipart.Form, error)
	Cookie(name string) (*http.Cookie, error)
	Cookies() []*http.Cookie
	SetCookie(cookie *http.Cookie)
	Bind(i any) error
	Validate(i any) error

	// --- per-request values (echo's own store, not ctx.SetData) ---
	Get(key string) any
	Set(key string, val any)

	// --- responses ---
	JSON(code int, i any) error
	JSONPretty(code int, i any, indent string) error
	JSONBlob(code int, b []byte) error
	XML(code int, i any) error
	String(code int, s string) error
	HTML(code int, html string) error
	Blob(code int, contentType string, b []byte) error
	Stream(code int, contentType string, r io.Reader) error
	File(file string) error
	Attachment(file, name string) error
	Inline(file, name string) error
	Render(code int, name string, data any) error
	NoContent(code int) error
	Redirect(code int, url string) error

	// Echo is the escape hatch to the underlying instance.
	Echo() *echo.Echo

	BindWithValidate(payload IValidateContext) IError
	BindOnly(payload any) IError
	GetPageOptions() *PageOptions
	GetPageOptionsWithAllowed(allowed ...string) *PageOptions
}

IHTTPContext is the per-request HTTP context: it is an IContext (all capabilities) plus the request/response surface of echo. Same name as v1.

echo v5 turned Context from an interface into a struct, so this interface can no longer embed it. The methods handlers actually use are declared here instead and satisfied by the embedded *echo.Context — call sites are unchanged (`c.JSON`, `c.Param`, `c.Bind` … still work), and anything not listed is reachable through Echo().

type IHTTPModule

type IHTTPModule interface {
	Routes(e *Server)
}

IHTTPModule registers the module's routes.

The signature is the one services already write by hand (func NewNoteHTTP(e *core.Server)), so an existing registration function becomes a method without changing a line of its body.

It returns nothing because the calls inside it do not: e.GET and friends return an echo.RouteInfo, never an error.

type IHealthModule

type IHealthModule interface {
	HealthChecks() []HealthCheck
}

IHealthModule reports dependencies the framework cannot see by itself — a partner API, a search index, a license server.

Each check's Name is prefixed with the module's, so two modules that both call a check "api" stay two entries in the report rather than one silently overwriting the other.

type IJobModule

type IJobModule interface {
	Jobs(reg *JobRegistry) IError
}

IJobModule registers the module's job definitions — what may be triggered, not what is scheduled.

Every role that triggers or runs a job needs its definition, including an API role that has no scheduler at all. Use ICronModule for the ones that also fire on a clock.

type IJobQueue

type IJobQueue interface {
	// Enqueue makes a run available, respecting run.ScheduledAt for delayed and
	// retried work.
	Enqueue(ctx context.Context, run *JobRun) IError
	// Reserve blocks until a run from one of queues is due, or ctx is done.
	Reserve(ctx context.Context, queues []string) (*JobRun, AckFunc, IError)
	// Remove drops a not-yet-reserved run, reporting whether it was there. It is
	// how a queued run is canceled without ever executing.
	Remove(ctx context.Context, runID string) (bool, IError)
	// Len reports how many runs are waiting (for metrics/tests).
	Len(ctx context.Context) (int, IError)
	Close() IError
}

IJobQueue is the delivery mechanism between whatever creates a run (the scheduler, a manual trigger, a retry) and the workers that execute it.

The queue only moves runs around; statuses and history live in IJobStore. Keeping them apart is what lets you run an in-memory queue over a durable store, or swap in Redis later without touching a single handler.

func NewMemoryJobQueue

func NewMemoryJobQueue() IJobQueue

NewMemoryJobQueue creates an in-process queue.

type IJobStore

type IJobStore interface {
	Create(ctx context.Context, run *JobRun) IError
	Update(ctx context.Context, run *JobRun) IError
	Get(ctx context.Context, id string) (*JobRun, IError)
	List(ctx context.Context, f JobRunFilter) (*Page[JobRun], IError)

	// FindActive returns the non-terminal run of jobName carrying idemKey, or
	// (nil, nil) when there is none. It is what makes triggering idempotent.
	FindActive(ctx context.Context, jobName, idemKey string) (*JobRun, IError)
	// RunningIDs lists the runs of jobName currently in RunRunning.
	RunningIDs(ctx context.Context, jobName string) ([]string, IError)

	RequestCancel(ctx context.Context, id, by, reason string) IError
	IsCancelRequested(ctx context.Context, id string) (bool, IError)

	AppendLogs(ctx context.Context, entries []JobLog) IError
	Logs(ctx context.Context, runID string, afterSeq int64, limit int) ([]JobLog, IError)

	// Purge deletes runs finished before runsBefore and logs older than
	// logsBefore, returning how many rows went away.
	Purge(ctx context.Context, runsBefore, logsBefore time.Time) (int64, IError)

	Close() IError
}

IJobStore persists runs and (optionally) their logs. It is the extension point for "where do job records live": the in-memory implementation below is the default, the jobstore package ships a repository/GORM-backed one, and a service can implement its own.

Methods take a context.Context because the store is app-scoped, not request-scoped.

func NewMemoryJobStore

func NewMemoryJobStore() IJobStore

NewMemoryJobStore creates an in-memory store.

type ILLM

type ILLM interface {
	// Generate runs one completion to the end.
	Generate(req LLMRequest) (LLMResponse, IError)
	// Stream starts a generation and returns it as deltas arrive. The caller
	// must Close the result.
	Stream(req LLMRequest) (LLMStream, IError)
	// CountTokens reports what req would cost as input, without running it.
	// Providers that have no counting endpoint return ErrLLMUnsupported rather
	// than an estimate — a wrong number is worse than no number, because it is
	// trusted.
	CountTokens(req LLMRequest) (int, IError)
	// Capabilities is what this model supports.
	Capabilities() LLMCapabilities
	// Model is the model id calls default to.
	Model() string
	// Provider names the service behind this handle ("anthropic", "openai",
	// "memory", ""). It is a label for logs and metrics, not a switch to branch
	// on — branch on Capabilities instead.
	Provider() string
	// Enabled reports whether this is a real model.
	Enabled() bool
	// Unwrap returns the driver's underlying client for provider-specific work
	// this interface does not cover. It may be nil.
	Unwrap() any
	// WithContext returns a handle bound to a different context.
	WithContext(ctx context.Context) ILLM
	// Close releases whatever the driver holds. Owned by App.Shutdown.
	Close() IError
}

ILLM generates text from a language model.

core.LLM(ctx) is never nil: a service with no AI_* configuration gets a disabled model whose every call fails with LLM_DISABLED.

Methods take no context — the handle is already bound to the request or run that produced it. Use WithContext for a background deadline that must outlive the request.

func LLM

func LLM(ctx context.Context) ILLM

LLM returns the application's language model bound to ctx.

Like core.Requester and core.Mailer it is a function rather than a method on IContext: a generation is not a capability of the request, it is a thing you do with the request's deadline attached — and IContext is already the interface everything in a service depends on, so it stays small.

resp, err := core.LLM(c).Generate(core.LLMRequest{Messages: ...})

ctx is anything carrying the App — an IContext from a handler or a job, or a plain context.Context derived from one. A context from nowhere gets the disabled model rather than nil, so a call site never has to nil-check.

func NewMemoryLLM

func NewMemoryLLM(replies ...string) ILLM

NewMemoryLLM returns a model that records requests and returns canned replies, so a test can assert on what a service would have asked a model:

m := core.NewMemoryLLM("Bangkok")
app, _ := core.NewApp(env, core.WithLLM(m))
...
calls := core.LLMCalls(m)
require.Len(t, calls, 1)
assert.Contains(t, calls[0].System, "answer in one word")

Replies are consumed in order. Running out is an error rather than a repeat of the last one: a service that called the model more often than the test scripted has changed behaviour, and silently handing it another answer is how that goes unnoticed. With no replies scripted at all it echoes the last user message, so a test that does not care what the model said needs no setup.

It runs the same request validation a driver does, so a malformed request fails the test rather than passing it.

func NewNoopLLM

func NewNoopLLM() ILLM

NewNoopLLM returns a model that refuses every call. It is what a service with no AI_* configuration gets, so the failure is a clear error rather than a nil dereference.

type ILifecycleModule

type ILifecycleModule interface {
	Start(app *App) IError
	Stop(ctx context.Context) IError
}

ILifecycleModule is background work the module owns.

Start must not block. Stop runs during the drain — after requests have finished, before any connection pool is closed — so a stopping module may still use the database.

type ILimiter

type ILimiter interface {
	// Acquire takes a slot for key. It returns ok=false immediately when the
	// limit is reached; release must be called when the work is done.
	// limit <= 0 means unlimited.
	Acquire(ctx context.Context, key string, limit int) (release func(), ok bool)
	// Count reports how many slots of key are held right now.
	Count(ctx context.Context, key string) int
}

ILimiter caps how many runs may hold a given key at once. Two keys are used: "job:<name>" for JobDef.MaxConcurrent and "queue:<name>" for a queue limit.

The default implementation counts in process, which is exactly right while the service runs as a single replica. Scaling to several replicas is a matter of supplying a Redis-backed implementation here — the runner and the handlers do not change.

func NewInProcessLimiter

func NewInProcessLimiter() ILimiter

NewInProcessLimiter creates a limiter that counts within this process.

func NewRedisLimiterWithClient

func NewRedisLimiterWithClient(rdb redis.UniversalClient, opts ...LimiterOption) ILimiter

NewRedisLimiterWithClient wraps an existing redis client, for a client built with options this package does not expose — or for a test. rdb is required; prefer NewRedisLimiter, which takes it from the cache the App already has.

type ILock

type ILock interface {
	// Key is the lock's key, without the cache prefix.
	Key() string
	// Extend pushes the expiry out. It fails once the lock has been lost, which
	// is the signal to stop the work it was guarding.
	Extend(ttl time.Duration) IError
	// Unlock releases the lock, and only ever releases *this* holder's lock.
	// Safe to call twice, and safe to defer.
	Unlock() IError
}

ILock is a lock held across processes. It always expires: a holder that crashes releases it by doing nothing, so one bad deploy cannot wedge a queue forever.

type ILogger

type ILogger interface {
	Debug(msg string, args ...any)
	Info(msg string, args ...any)
	Warn(msg string, args ...any)
	Error(msg string, args ...any)
	// With returns a child logger with the given attributes pinned.
	With(args ...any) ILogger
	// Slog exposes the underlying *slog.Logger for advanced use.
	Slog() *slog.Logger
}

ILogger is the structured logger. Same name/verbs as v1 so callers do not relearn, but it is backed by the standard library's log/slog and uses slog-style structured arguments (msg, key, value, key, value, ...).

func NewLogger

func NewLogger(env IENV) ILogger

NewLogger builds an ILogger from configuration: JSON output by default, a human-friendly text handler when LogSimple is set, at the configured level.

func NewLoggerSimple

func NewLoggerSimple() ILogger

NewLoggerSimple returns a readable text logger at info level (no config needed), coloured when stdout is a terminal.

func NewLoggerTo

func NewLoggerTo(w io.Writer, env IENV) ILogger

NewLoggerTo is NewLogger writing to a specific destination (used in tests).

type IMQ

type IMQ interface {
	// Publish sends msg and waits for the broker to confirm it. A nil error
	// means the broker has taken responsibility for the message.
	Publish(exchange, key string, msg any) IError
	// PublishWith is Publish with the message properties spelled out.
	PublishWith(exchange, key string, msg any, opts PublishOptions) IError

	// DeclareExchange creates an exchange if it does not exist. Declaring one
	// that exists with different settings is an error from the broker, which is
	// the point: it catches a topology change nobody applied.
	DeclareExchange(cfg ExchangeConfig) IError
	// DeclareQueue creates a queue if it does not exist and reports its depth.
	DeclareQueue(cfg QueueConfig) (QueueInfo, IError)
	// BindQueue routes messages from an exchange into a queue.
	BindQueue(queue, exchange, key string, args ...map[string]any) IError
	// UnbindQueue removes a binding.
	UnbindQueue(queue, exchange, key string, args ...map[string]any) IError
	// DeleteQueue removes a queue and everything in it.
	DeleteQueue(name string) IError
	// PurgeQueue empties a queue and reports how many messages it dropped.
	PurgeQueue(name string) (int, IError)
	// QueueInfo reports a queue's depth without declaring anything. It fails if
	// the queue does not exist.
	QueueInfo(name string) (QueueInfo, IError)

	// Ping reports whether the broker is reachable — for a readiness probe. It
	// reconnects if the connection has dropped, so a probe built on it recovers
	// on its own.
	Ping() IError
	// Enabled reports whether this is a real publisher. False for the disabled
	// publisher a service with no MQ_* configuration gets.
	Enabled() bool
	// WithContext returns a handle bound to a different context (escape hatch
	// for work that must outlive the request).
	WithContext(ctx context.Context) IMQ
	// Close releases the connection. Owned by App.Shutdown; call it yourself
	// only for a publisher built outside an App.
	Close() IError
}

IMQ is the message-queue publisher (same name as v1). Publish uses the bound context from ctx.MQ(); the payload is JSON-encoded unless it is []byte.

ctx.MQ() is never nil: a service with no MQ_* configuration gets a disabled publisher whose every call fails with MQ_DISABLED, naming the missing configuration, rather than panicking on a nil interface.

func NewNoopMQ

func NewNoopMQ() IMQ

NewNoopMQ returns a publisher that refuses every operation. It is what a service with no MQ_* configuration gets, so the failure is a clear error instead of a nil dereference.

type IMQConsumer

type IMQConsumer interface {
	// On registers a handler for a queue. Registering a queue twice replaces the
	// first handler.
	On(queue string, h MQHandler) IMQConsumer
	// OnQueue is On with the queue declared and bound first, so a service brings
	// up its own topology rather than depending on somebody having run a script.
	OnQueue(cfg ConsumeQueue, h MQHandler) IMQConsumer
	// Start opens the connection and begins consuming. It returns as soon as the
	// consumers are live; the work happens in the background.
	Start() IError
	// Stop stops consuming and waits for in-flight handlers, up to the deadline
	// on ctx. Safe to call more than once.
	Stop(ctx context.Context) IError
	// Running reports whether Start has run and Stop has not.
	Running() bool
}

IMQConsumer turns queues into handlers, the way the HTTP server turns routes into handlers. It owns the connection, the prefetch, the acknowledgement, the per-message context, the panic recovery, the reconnect and the drain.

c := app.NewMQConsumer(core.WithMQPrefetch(20))
c.On("orders", func(ctx core.IMQContext, d *core.Delivery) error {
    order, err := core.BindDelivery[Order](d)
    if err != nil {
        return err // malformed: dead-letter it, redelivery will not help
    }
    return process(ctx, order)
})
if err := c.Start(); err != nil { ... }

type IMQContext

type IMQContext interface {
	IContext
	// Delivery is the message being handled.
	Delivery() *Delivery
}

IMQContext is the per-delivery context: an IContext plus the message that caused it. Same name as v1, where it was the consumer's context too.

type IMQModule

type IMQModule interface {
	Consumers(c IMQConsumer)
}

IMQModule registers the module's queue consumers.

type IMailer

type IMailer interface {
	// Send delivers msg, bounded by the handle's context.
	Send(msg EmailMessage) IError
	// SendTemplate renders the template registered under name and sends it. It
	// fills HTML from "<name>.html" and Text from "<name>.txt", whichever exist,
	// and leaves a body the caller already set alone.
	SendTemplate(msg EmailMessage, name string, data any) IError
	// Render returns what SendTemplate would send, without sending it — for a
	// preview route, or a test that asserts on the wording.
	Render(name string, data any) (html string, text string, err IError)
	// Ping opens a connection to the SMTP server and closes it, for a readiness
	// probe.
	Ping() IError
	// Enabled reports whether this is a real mailer.
	Enabled() bool
	// WithContext returns a handle bound to a different context.
	WithContext(ctx context.Context) IMailer
	// Close releases whatever the mailer holds. Owned by App.Shutdown.
	Close() IError
}

IMailer sends email.

core.Mailer(ctx) is never nil: a service with no EMAIL_* configuration gets a disabled mailer whose every call fails with MAILER_DISABLED.

func Mailer

func Mailer(ctx context.Context) IMailer

Mailer returns the application's mailer bound to ctx.

It is a function rather than a method on IContext, for the same reason core.Requester is: sending an email is not a capability of the request — it is something code does, with the request's deadline and trace attached. Taking only a context.Context is what lets a service that knows nothing about this framework send one:

func (s *NotificationService) SendWelcome(ctx context.Context, u User) error {
    return core.Mailer(ctx).SendTemplate(msg, "welcome", u)
}

ctx is anything carrying the App — an IContext from a handler or a job, or any context.Context derived from one.

A context from nowhere — context.Background() in a script or an early test — gets the disabled mailer rather than nil, so a call site never has to nil-check. Every call on it fails with MAILER_DISABLED.

func NewMemoryMailer

func NewMemoryMailer(templates ...*MailTemplates) IMailer

NewMemoryMailer returns a mailer that records messages instead of delivering them, so a test can assert on what a service would have sent:

m := core.NewMemoryMailer(templates)
app, _ := core.NewApp(env, core.WithMailer(m))
...
sent := core.SentMail(m)
require.Len(t, sent, 1)
assert.Contains(t, sent[0].HTML, "reset your password")

It runs the same validation the real mailer does, so a message the SMTP server would have rejected fails the test rather than passing it.

func NewNoopMailer

func NewNoopMailer() IMailer

NewNoopMailer returns a mailer that refuses every operation. It is what a service with no EMAIL_* configuration gets, so the failure is a clear error instead of a nil dereference.

type IMeter

type IMeter interface {
	// Enabled reports whether metrics actually leave the process.
	Enabled() bool
	// WithContext binds the meter to ctx, so what it records carries that
	// request or run's trace.
	WithContext(ctx context.Context) IMeter

	// Count adds n to a counter — "how many times did this happen".
	Count(name string, n int64, opts ...MetricOption)
	// Gauge records a value that moves up and down — queue depth, pool size.
	// Only the latest value of an interval means anything.
	Gauge(name string, value float64, opts ...MetricOption)
	// Distribution records one sample of something whose spread matters —
	// latency, payload size. Sentry keeps the percentiles, not just the mean.
	Distribution(name string, sample float64, opts ...MetricOption)
	// Duration is Distribution for a length of time, recorded in milliseconds
	// so every timing in the org is comparable.
	Duration(name string, d time.Duration, opts ...MetricOption)
}

IMeter records the numbers a service watches over time — orders paid, queue depth, upload size. They arrive in Sentry alongside the traces and logs of the same request, so a spike can be opened and read rather than just seen.

Like every other capability it is reached through the context (`ctx.Meter()`), and it is never nil: with metrics off every call is a no-op, so call sites never guard.

type IModel

type IModel interface {
	TableName() string
}

IModel is implemented by repository models. TableName keeps parity with v1 and GORM's convention.

type IModule

type IModule interface {
	// Name identifies the module. It must match [a-z0-9][a-z0-9_-]* and be
	// unique within a ModuleSet: it prefixes the module's health checks and
	// keys its entry in the devtools report.
	Name() string
}

IModule is one feature of a service, in a shape the framework can assemble.

Without it the registration of a single feature is spread across the composition root by kind rather than by feature — routes in cmd/api.go, jobs in cmd/worker.go, consumers somewhere else — which is the layering the modules/ convention rejected everywhere else in a service. Worse, half of it can be forgotten silently: a route nobody registered is a 404 found in QA, a cron nobody armed is a job that simply never runs, and both compile.

A module declares everything it attaches in one file. What a role actually uses is then the Runner's decision, not the module's: a process with no HTTP server never calls Routes, so one module list serves every role.

The only thing required is a name — every other capability is an optional interface (IHTTPModule, IJobModule, ICronModule, IMQModule, IHealthModule, ILifecycleModule) implemented only by the modules that have one.

Modules are compile-time: the composition root still names every one of them. That is deliberate — see NewModules.

type IMongoDB

type IMongoDB interface {

	// FindOne decodes the first match into dest. The error wraps
	// ErrDocumentNotFound when nothing matches.
	FindOne(dest any, collection string, filter any, opts ...MongoFindOptions) IError
	// Find decodes every match into dest (a pointer to a slice). Without a Limit
	// it reads the whole result set into memory — pass one, use MongoPaginate,
	// or stream with FindCursor.
	Find(dest any, collection string, filter any, opts ...MongoFindOptions) IError
	// FindCursor returns the cursor instead of the documents, for a result set
	// too large to hold. Close it, and read it with MongoEach.
	FindCursor(collection string, filter any, opts ...MongoFindOptions) (*mongo.Cursor, IError)
	// Count counts matches. An empty filter counts the collection.
	Count(collection string, filter any) (int64, IError)
	// EstimatedCount reads the collection's metadata instead of counting, which
	// is instant on a large collection and approximate after an unclean
	// shutdown. It cannot take a filter.
	EstimatedCount(collection string) (int64, IError)
	// Exists reports whether anything matches, without transferring it.
	Exists(collection string, filter any) (bool, IError)
	// Distinct decodes the distinct values of a field into dest.
	Distinct(dest any, collection, field string, filter any) IError

	// Aggregate runs a pipeline into dest. The pipeline is passed to the driver
	// as it is — []bson.M, bson.A or mongo.Pipeline — so every stage is
	// available, including $lookup, $facet, $graphLookup, $unionWith, $merge
	// and $out.
	//
	// Set AllowDiskUse for anything that groups or sorts a large collection.
	Aggregate(dest any, collection string, pipeline any, opts ...MongoAggregateOptions) IError
	// AggregateCursor returns the cursor instead of the documents, for a
	// pipeline whose output does not fit in memory. Close it.
	AggregateCursor(collection string, pipeline any, opts ...MongoAggregateOptions) (*mongo.Cursor, IError)

	// InsertOne stores a document and returns its id as a hex string — one that
	// can be handed back to a filter. (v2.2 returned the driver's Go rendering,
	// `ObjectID("…")`, which matched nothing when it was.)
	InsertOne(collection string, document any) (string, IError)
	// InsertMany stores documents and returns their ids, in order.
	InsertMany(collection string, documents []any) ([]string, IError)
	// UpdateOne applies update (bson.M{"$set": …}) to the first match.
	UpdateOne(collection string, filter, update any, opts ...MongoUpdateOptions) (MongoUpdateResult, IError)
	// UpdateMany applies update to every match.
	UpdateMany(collection string, filter, update any, opts ...MongoUpdateOptions) (MongoUpdateResult, IError)
	// ReplaceOne swaps the whole document, keeping its id.
	ReplaceOne(collection string, filter, document any, opts ...MongoUpdateOptions) (MongoUpdateResult, IError)
	// DeleteOne removes the first match and reports how many it removed.
	DeleteOne(collection string, filter any) (int64, IError)
	// DeleteMany removes every match.
	DeleteMany(collection string, filter any) (int64, IError)
	// BulkWrite sends many writes in one round trip. Ordered stops at the first
	// failure; unordered runs them all and reports what failed.
	BulkWrite(collection string, models []mongo.WriteModel, ordered bool) (MongoBulkResult, IError)

	// FindOneAndUpdate updates the first match and decodes it into dest, in one
	// atomic step. This is how a job is claimed or a counter is read as it is
	// incremented — a Find followed by an Update is a race.
	FindOneAndUpdate(dest any, collection string, filter, update any, opts ...MongoFindModifyOptions) IError
	// FindOneAndReplace swaps the first match and decodes it into dest.
	FindOneAndReplace(dest any, collection string, filter, document any, opts ...MongoFindModifyOptions) IError
	// FindOneAndDelete removes the first match and decodes it into dest.
	FindOneAndDelete(dest any, collection string, filter any, opts ...MongoFindModifyOptions) IError

	// EnsureIndex creates an index when it is missing. Run it at startup; it is
	// safe to call on every boot.
	EnsureIndex(collection string, index MongoIndex) IError
	// EnsureIndexes creates several in one round trip.
	EnsureIndexes(collection string, indexes ...MongoIndex) IError
	// DropIndex removes one by name.
	DropIndex(collection, name string) IError
	// ListIndexes returns the index documents of a collection.
	ListIndexes(collection string) ([]map[string]any, IError)
	// DropCollection removes a collection and everything in it.
	DropCollection(collection string) IError
	// ListCollections returns the collection names of the database.
	ListCollections() ([]string, IError)

	// Transaction runs fn inside a session transaction, committing when it
	// returns nil and aborting when it returns an error or panics. The handle
	// passed to fn is the one to use — the outer one is not in the transaction.
	//
	// Mongo only offers transactions on a replica set or a sharded cluster; a
	// standalone server fails with a message saying so.
	Transaction(fn func(tx IMongoDB) error) IError
	// Watch opens a change stream on a collection, or on the whole database
	// when collection is "". Close it. Needs a replica set.
	Watch(collection string, pipeline any) (*mongo.ChangeStream, IError)

	// Ping checks the connection — for a readiness probe.
	Ping() IError
	// Enabled reports whether Mongo is configured.
	Enabled() bool
	// Name is the database every operation runs against.
	Name() string
	// Collection is the driver handle, for anything this interface does not
	// cover. Nil when disabled. Use the bound context from Context() with it.
	Collection(name string) *mongo.Collection
	// Database is the driver's database handle (GridFS, RunCommand). Nil when
	// disabled.
	Database() *mongo.Database
	// Client is the driver's client. Nil when disabled.
	Client() *mongo.Client
	// Context is the context this handle is bound to, for driver calls made
	// through Collection.
	Context() context.Context
	// WithContext returns a handle bound to another context.
	WithContext(ctx context.Context) IMongoDB
	// WithReadPreference returns a handle whose reads may go elsewhere —
	// readpref.SecondaryPreferred() to keep a heavy report off the primary.
	// Writes always go to the primary regardless.
	WithReadPreference(pref *readpref.ReadPref) IMongoDB
	// Close disconnects. Owned by App.Shutdown.
	Close() IError
}

IMongoDB is the Mongo abstraction (same name as v1). Methods use the bound context from ctx.DBMongo(), so they take no ctx.

It no longer hides the driver. The goal of doing so was to keep callers off mongo-driver, but a caller has to write bson.M for every filter anyway — so the abstraction never bought isolation, it only put aggregation, transactions and indexes out of reach. Collection(), Database() and Client() are part of the interface; the helpers around them cover what most code needs, and nothing the driver can do is off limits.

func NewNoopMongoDB

func NewNoopMongoDB() IMongoDB

NewNoopMongoDB returns a Mongo handle that refuses every operation.

type IParamsDescriber

type IParamsDescriber interface {
	ParamSchema() []ParamField
}

IParamsDescriber is implemented by a parameter type that describes itself. It is the third way to publish a schema, for when the description belongs next to the struct rather than on the JobDef — and the only way to build one that depends on runtime state (values loaded from the database, say).

func (ReportParams) ParamSchema() []core.ParamField {
    return core.Params(
        core.DateParam("date").Required(),
        core.EnumParam("status", loadStatuses()...),
    )
}

JobDef.Params still wins when both are given.

type IPubSub

type IPubSub interface {
	// Publish sends msg to a channel. string/[]byte go out as they are,
	// everything else is JSON-encoded — the same rule ICache.Set follows.
	Publish(channel string, msg any) IError
	// Subscribe listens on exact channel names.
	Subscribe(channels ...string) (ISubscription, IError)
	// PSubscribe listens on glob patterns ("order.*", "user.?", "cache:[ab]*").
	PSubscribe(patterns ...string) (ISubscription, IError)
	// Channel is the wire name a logical channel travels under: the cache
	// prefix plus the name. Only needed to talk to a publisher that is not
	// built on this framework.
	Channel(name string) string
	// Enabled reports whether there is a real connection behind this handle.
	Enabled() bool
	// WithContext returns a handle bound to another context.
	WithContext(ctx context.Context) IPubSub
	// Close releases the handle. Subscriptions are closed individually.
	Close() IError
}

IPubSub is redis publish/subscribe: fan-out to every listener, right now.

It is not a queue and must not be used as one. A message published while nobody is listening is gone, there is no acknowledgement, no redelivery and no persistence. That makes it right for cache invalidation, config reloads, presence and live updates — and wrong for work that must not be lost, which belongs on IMQ or the job queue.

type IPusher

type IPusher interface {
	// Send delivers to one device token.
	Send(token string, msg PushMessage) IError
	// SendMulticast delivers to many tokens, in batches of 500, and reports each
	// one. A token failing is not an error — read BatchResult.
	SendMulticast(tokens []string, msg PushMessage) (*BatchResult, IError)
	// SendToTopic delivers to everyone subscribed to a topic.
	SendToTopic(topic string, msg PushMessage) IError
	// SendToCondition delivers to the devices matching a topic condition, e.g.
	// "'news' in topics && 'th' in topics".
	SendToCondition(condition string, msg PushMessage) IError
	// Subscribe adds tokens to a topic.
	Subscribe(topic string, tokens ...string) (*BatchResult, IError)
	// Unsubscribe removes tokens from a topic.
	Unsubscribe(topic string, tokens ...string) (*BatchResult, IError)
	// Validate checks a message against the provider without delivering it —
	// FCM's dry run.
	Validate(token string, msg PushMessage) IError
	// Enabled reports whether this is a real pusher.
	Enabled() bool
	// WithContext returns a handle bound to a different context.
	WithContext(ctx context.Context) IPusher
}

IPusher sends push notifications (FCM).

core.Pusher(ctx) is never nil: a service with no Firebase credentials gets a disabled pusher whose every call fails with PUSH_DISABLED.

func NewMemoryPusher

func NewMemoryPusher() IPusher

NewMemoryPusher returns a pusher that records deliveries instead of making them, so a test can assert on what a service would have sent:

p := core.NewMemoryPusher()
app, _ := core.NewApp(env, core.WithPusher(p))
...
sent := core.SentPushes(p)
require.Len(t, sent, 1)
assert.Equal(t, "Order shipped", sent[0].Message.Title)

func NewNoopPusher

func NewNoopPusher() IPusher

NewNoopPusher returns a pusher that refuses every operation. It is what a service with no Firebase credentials gets, so the failure is a clear error instead of a nil dereference.

func Pusher

func Pusher(ctx context.Context) IPusher

Pusher returns the application's push sender bound to ctx.

It is a function rather than a method on IContext, for the same reason core.Requester and core.Mailer are: sending a notification is not a capability of the request — it is something code does. Taking only a context.Context is what lets a service that knows nothing about this framework send one:

func (s *OrderService) NotifyShipped(ctx context.Context, o Order) error {
    return core.Pusher(ctx).Send(o.DeviceToken, msg)
}

A context carrying no App gets the disabled pusher rather than nil, so a call site never has to nil-check. Every call on it fails with PUSH_DISABLED.

type IRequester

type IRequester interface {
	// R returns a *resty.Request bound to the context — configure it with the
	// full go-resty API, then run it with Send.
	R() *resty.Request
	// Send executes a request built via R(), returning a core.IError on a
	// transport failure (code NETWORK_ERROR, 500) or a non-2xx status (the
	// remote error code/message are reused when the body carries them).
	Send(req *resty.Request, method, url string) (*resty.Response, IError)
	// WithContext returns a copy bound to a different context (escape hatch).
	WithContext(ctx context.Context) IRequester
	// Resty returns the shared client for startup-time configuration (retries,
	// TLS, base URL, middleware). Configure it once, not per request.
	Resty() *resty.Client
}

IRequester is the HTTP client. Same name as v1; backed by go-resty and reused across requests.

You build requests with the full go-resty API via R() (headers, query, form, files, auth, output streaming, tracing, …) and run them with Send, which is the only thing the framework wraps: it binds the request context and converts every failure — transport error or non-2xx status — into a core.IError.

var out UserDTO
resp, err := r.Send(r.R().SetHeader("X-Token", tok).SetResult(&out), http.MethodGet, url)
if err != nil {
    return err // IError, ready to return from a handler
}

Add SetError(&failure) when the upstream's error body carries more than a code and a message — the IError is returned either way, and the struct holds whatever the caller has to branch on.

func NewRequester

func NewRequester(env IENV, log ILogger) IRequester

NewRequester builds the shared HTTP client (reused, pool kept alive). env is accepted for symmetry with the other constructors and may be nil.

func NewRequesterWithClient

func NewRequesterWithClient(rc *resty.Client) IRequester

NewRequesterWithClient wraps a fully-configured *resty.Client — use this to enable any client-level go-resty feature (retries, middleware, TLS config, base URL, proxy, hooks) and wire it via core.WithRequester(...).

func Requester

func Requester(ctx context.Context) IRequester

Requester returns the application's HTTP client bound to ctx.

It is a function rather than a context method because an outgoing call is not a capability of the request — it is a thing you do, with the request's deadline and trace attached:

resp, err := core.Requester(c).Send(req, http.MethodGet, url)

ctx is anything that carries the App — an IContext from a handler or a job, or any context.Context derived from one, so a function that took only a context.Context can still make the call. Every context an App built carries it, which is what keeps the client, its connection pool and its Sentry instrumentation the ones configured at startup.

A context from nowhere — context.Background() in a script or an early test — gets a plain client with the default timeout instead of nil, so a call site never has to nil-check. That client is not instrumented: with no App there is no configuration and no tracker to report to.

type ISentry

type ISentry interface {
	// Enabled reports whether events actually leave the process.
	Enabled() bool
	// WithContext binds the tracker to ctx (its hub, user, tags and breadcrumbs).
	WithContext(ctx context.Context) ISentry

	// CaptureError reports err with everything the bound context knows. Returns
	// the Sentry event id ("" when nothing was sent).
	CaptureError(err error, opts ...CaptureOption) string
	// CaptureMessage reports a standalone message.
	CaptureMessage(msg string, level Level, opts ...CaptureOption) string
	// Recover reports a recovered panic value at fatal level.
	Recover(panicValue any, opts ...CaptureOption) string

	// Breadcrumb records a step on the bound context's trail.
	Breadcrumb(b Breadcrumb)
	// SetTag pins an indexed tag on every later event of this context.
	SetTag(key, value string)
	// SetContextData pins a named block of structured data on this context.
	SetContextData(name string, data map[string]any)

	// StartTransaction opens a performance transaction bound to this context.
	StartTransaction(name, op string) ISpan
	// Meter records measurements on this context's trace. Never nil.
	Meter() IMeter
	// SendCheckIn reports to a cron monitor and returns the check-in id.
	SendCheckIn(c CheckIn) string

	// Flush blocks until queued events are sent, or timeout elapses.
	Flush(timeout time.Duration) bool
	// Close flushes and releases the transport.
	Close() IError
	// Hub exposes the underlying hub (escape hatch); nil when disabled.
	Hub() *sentry.Hub
}

ISentry is the error tracker. Like every other capability it is reached through the context — ctx.Sentry() returns a tracker already bound to the request/run, so captures land on that unit of work's own scope.

It is never nil: with no DSN configured every method is a no-op, so callers never guard.

func NewNoopSentry

func NewNoopSentry() ISentry

NewNoopSentry returns a tracker that discards everything. It is what services without a DSN get, so the capture path is identical in every environment.

type ISpan

type ISpan interface {
	// Context returns the context carrying this span; pass it down so child work
	// attaches to it.
	Context() context.Context
	// TraceID is the id shared by every span, log line and Sentry event of this
	// unit of work.
	TraceID() string
	SetTag(key, value string)
	SetData(key string, value any)
	// Child starts a nested span (e.g. one query inside a request).
	Child(op, description string) ISpan
	// Finish closes the span, marking it failed when err is non-nil.
	Finish(err error)
	// Sentry exposes the underlying span (escape hatch); nil when disabled.
	Sentry() *sentry.Span
}

ISpan is a unit of work on the performance timeline (a transaction when it is the outermost one). Finish it exactly once, passing the error the work ended with — or nil.

type IStorage

type IStorage interface {

	// Put stores body under key, uploading in parts when it is large — so an
	// object of unknown size does not have to fit in memory.
	Put(key string, body io.Reader, opts ...StoragePutOptions) IError
	// PutBytes stores data under key.
	PutBytes(key string, data []byte, opts ...StoragePutOptions) IError
	// Get streams the object. Close it. The error wraps ErrObjectNotFound when
	// the key is absent.
	Get(key string) (io.ReadCloser, IError)
	// GetBytes reads the whole object into memory — for small objects only.
	GetBytes(key string) ([]byte, IError)
	// Stat returns an object's metadata without transferring it.
	Stat(key string) (StorageObject, IError)
	// Exists reports whether key is present. A missing key is not an error.
	Exists(key string) (bool, IError)
	// List returns the objects under a prefix, following pagination.
	List(prefix string, opts ...StorageListOptions) ([]StorageObject, IError)
	// Copy duplicates an object inside the bucket, server-side.
	Copy(srcKey, dstKey string) IError
	// Move copies then deletes: S3 has no rename.
	Move(srcKey, dstKey string) IError
	// Delete removes objects, in batches of 1000. Absent keys are not an error.
	Delete(keys ...string) IError
	// DeleteByPrefix removes everything under a prefix and returns how many
	// objects it deleted.
	DeleteByPrefix(prefix string) (int64, IError)

	// PresignGet returns a temporary URL that reads the object, for a client
	// that must not be given credentials.
	PresignGet(key string, ttl time.Duration, opts ...StoragePresignOptions) (string, IError)
	// PresignPut returns a temporary URL that writes the object, so a browser
	// can upload straight to the bucket instead of through the service. The
	// client must send the same Content-Type the link was signed with.
	PresignPut(key string, ttl time.Duration, opts ...StoragePutOptions) (string, IError)
	// PublicURL is the unsigned address of an object, from S3_PUBLIC_URL when
	// set (a CDN) and the endpoint otherwise. It says nothing about whether the
	// object is actually readable — that is the bucket's policy to decide.
	PublicURL(key string) string

	// Ping checks the bucket is reachable — for a readiness probe. It needs
	// permission to head the bucket, which object-scoped credentials may lack.
	Ping() IError
	// Enabled reports whether storage is configured.
	Enabled() bool
	// Bucket is the bucket every operation runs against.
	Bucket() string
	// Key is the full key an operation would use: the prefix plus the name.
	Key(key string) string
	// WithPrefix returns a handle that namespaces keys further, e.g.
	// store.WithPrefix("tenants/42") writes "tenants/42/<key>".
	WithPrefix(prefix string) IStorage
	// WithContext returns a handle bound to another context (escape hatch for
	// work that must outlive the request).
	WithContext(ctx context.Context) IStorage
	// S3 exposes the underlying client for anything this interface does not
	// cover. Nil for the memory and disabled backends, and it does not apply the
	// prefix — build keys with Key().
	S3() *s3.Client
}

IStorage is object storage (S3-compatible: AWS S3, MinIO, R2, Spaces).

ctx.Storage() returns a handle bound to the request context, so methods take no ctx: a cancelled request stops the upload it started.

func NewMemoryStorage

func NewMemoryStorage() IStorage

NewMemoryStorage returns in-process storage. Wire it like any other:

app, _ := core.NewApp(env, core.WithStorage(core.NewMemoryStorage()))

func NewNoopStorage

func NewNoopStorage() IStorage

NewNoopStorage returns storage that refuses every operation. It is what a service with no S3_* configuration gets, so the failure is a clear error instead of a nil dereference.

type IStoreBackedQueue

type IStoreBackedQueue interface {
	IJobQueue
	// SharesStore reports that Enqueue is redundant with writing the run.
	SharesStore() bool
}

IStoreBackedQueue is implemented by a queue whose storage *is* the store — the run's own row is the queue (see the jobstore package). For those the runner skips Enqueue entirely: writing the run is already what makes it available, and a second write is a race waiting to happen, because it can flip a run back to queued after another worker has claimed it — running it twice.

A queue that keeps its own storage (in-memory, Redis, RabbitMQ) does not implement this and gets the normal Enqueue call.

type ISubscriber

type ISubscriber interface {
	// On registers a handler for an exact channel. Registering a channel twice
	// replaces the first handler.
	On(channel string, h PubSubHandler) ISubscriber
	// OnPattern registers a handler for a glob ("order.*").
	OnPattern(pattern string, h PubSubHandler) ISubscriber
	// Start opens the subscriptions and begins dispatching. It returns as soon
	// as the subscriptions are live — the work happens in the background.
	Start() IError
	// Stop ends the subscriptions and waits for in-flight handlers, up to the
	// deadline on ctx. Safe to call more than once.
	Stop(ctx context.Context) IError
	// Running reports whether Start has run and Stop has not.
	Running() bool
}

ISubscriber turns a set of channels into handlers, the way the HTTP server turns routes into handlers. It owns the subscription, the panic recovery, the per-message context and the drain on shutdown.

sub := app.NewSubscriber()
sub.On("user.updated", func(ctx core.IContext, msg *core.PubSubMessage) error {
    user, err := core.BindMessage[User](msg)
    if err != nil {
        return err
    }
    return cacheUser(ctx, user)
})
if err := sub.Start(); err != nil { ... }

type ISubscription

type ISubscription interface {
	// C delivers messages until Close is called, and is then closed itself, so
	// `for msg := range sub.C()` ends cleanly.
	C() <-chan *PubSubMessage
	// Channels are the names (or patterns) this subscription listens on.
	Channels() []string
	// Close stops the subscription. Safe to call more than once.
	Close() IError
}

ISubscription is one live subscription. Always Close it — a subscription holds a connection of its own for as long as it lives.

type IValidate

type IValidate interface {
	Valid() IError
}

IValidate is implemented by request payloads that validate without a context.

type IValidateContext

type IValidateContext interface {
	Valid(ctx IContext) IError
}

IValidateContext is implemented by request payloads that validate with access to the context (e.g. for DB-backed rules). Same contract as v1.

type JobDef

type JobDef struct {
	// Name uniquely identifies the job. Required.
	Name string
	// Description is shown by the admin API/UI.
	Description string
	// Schedule makes the job run automatically. nil = manual-only.
	Schedule Schedule
	// Queue routes the job to a worker pool. Empty = DefaultQueue.
	Queue string
	// Timeout bounds a single run; the run context is canceled after it.
	// 0 = DefaultJobTimeout.
	Timeout time.Duration
	// StopGrace is how long the runner waits for a handler to return after the
	// run has been canceled, before giving up on it. 0 = DefaultStopGrace.
	StopGrace time.Duration
	// MaxAttempts is the total number of tries, including the first.
	// 0 or 1 = no automatic retry.
	MaxAttempts int
	// Backoff computes the delay before each retry. nil = exponential 1s→5m.
	Backoff BackoffFunc
	// MaxConcurrent limits how many runs of this job may execute at once.
	// 0 = unlimited, 1 = singleton.
	MaxConcurrent int
	// Concurrency decides what to do when the limit is hit.
	Concurrency ConcurrencyPolicy
	// Replayable allows operators to re-run a finished run. Default true; set
	// false for jobs where replaying is dangerous (payments, real emails).
	Replayable *bool
	// Params describes the parameters the job accepts, so an admin API can list
	// them and a UI can build a form. RegisterJob fills this in from the
	// parameter type; set it explicitly only to override what reflection found.
	Params []ParamField
	// Logs is the per-job log policy, overriding the runner default.
	// nil = use the runner's policy (LogOff unless configured).
	Logs *LogPolicy
	// RetainRuns / RetainLogs are TTLs used by the purge job.
	RetainRuns time.Duration
	RetainLogs time.Duration
}

JobDef is the definition of a job: everything that is true of *every* run of it. A run's own data (params, status, timing) lives in JobRun.

type JobFunc

type JobFunc func(c ICronjobContext) error

JobFunc is a job handler. The signature is unchanged from v1, so existing jobs keep working; the extra capabilities hang off the context.

type JobInfo

type JobInfo struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	// Schedule is empty for a manual-only job.
	Schedule      string `json:"schedule,omitempty"`
	Queue         string `json:"queue"`
	MaxAttempts   int    `json:"max_attempts"`
	MaxConcurrent int    `json:"max_concurrent,omitempty"`
	Concurrency   string `json:"concurrency"`
	Replayable    bool   `json:"replayable"`
	Paused        bool   `json:"paused"`
	// Params describes what the job accepts. Empty means it takes none.
	Params []ParamField `json:"params,omitempty"`
}

JobInfo is everything an operator (or an admin UI) needs to know about a job without running it — including the shape of its parameters.

type JobLog

type JobLog struct {
	RunID   string         `json:"run_id" gorm:"column:run_id;size:36;primaryKey"`
	Seq     int64          `json:"seq" gorm:"column:seq;primaryKey"`
	Attempt int            `json:"attempt" gorm:"column:attempt"`
	At      time.Time      `json:"at" gorm:"column:at"`
	Level   string         `json:"level" gorm:"column:level;size:8"`
	Message string         `json:"message" gorm:"column:message;type:text"`
	Attrs   map[string]any `json:"attrs,omitempty" gorm:"column:attrs;serializer:json;type:text"`
}

JobLog is one persisted log line of a run.

Seq orders the lines of a run and doubles as the paging cursor. It is offset by the attempt (see logSeqBase), so a retry continues after the previous attempt instead of colliding with it.

func (JobLog) TableName

func (JobLog) TableName() string

TableName implements IModel.

type JobRegistry

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

JobRegistry holds the job definitions of a service. It is filled at startup and read by the runner and the scheduler.

func NewJobRegistry

func NewJobRegistry() *JobRegistry

NewJobRegistry creates an empty registry.

func (*JobRegistry) Def

func (r *JobRegistry) Def(name string) (JobDef, bool)

Def returns a job's definition.

func (*JobRegistry) Info

func (r *JobRegistry) Info() []JobInfo

Info returns the full description of every job, ordered by name — what an admin API serves so a UI can list the jobs and build a form for each one's parameters.

func (*JobRegistry) IsPaused

func (r *JobRegistry) IsPaused(name string) bool

IsPaused reports whether the job is paused.

func (*JobRegistry) List

func (r *JobRegistry) List() []JobDef

List returns every definition, ordered by name.

func (*JobRegistry) Params

func (r *JobRegistry) Params(name string) []ParamField

Params returns the parameter schema of a job (nil when it takes none).

func (*JobRegistry) Pause

func (r *JobRegistry) Pause(name string) IError

Pause stops a job from being scheduled or triggered. Runs already queued are left alone.

func (*JobRegistry) Register

func (r *JobRegistry) Register(def JobDef, fn JobFunc) IError

Register adds a job with no parameters. Use RegisterJob for typed params.

func (*JobRegistry) Resume

func (r *JobRegistry) Resume(name string) IError

Resume undoes Pause.

type JobRun

type JobRun struct {
	ID      string          `json:"id" gorm:"column:id;primaryKey;size:36"`
	JobName string          `json:"job_name" gorm:"column:job_name;size:191;index:idx_job_runs_job_status,priority:1"`
	Queue   string          `json:"queue" gorm:"column:queue;size:64"`
	Params  json.RawMessage `json:"params,omitempty" gorm:"column:params;type:text"`

	Status      RunStatus `` /* 126-byte string literal not displayed */
	Trigger     Trigger   `json:"trigger" gorm:"column:trigger;size:16"`
	TriggeredBy string    `json:"triggered_by,omitempty" gorm:"column:triggered_by;size:191"`
	IdemKey     string    `json:"idem_key,omitempty" gorm:"column:idem_key;size:191;index"`

	Attempt     int `json:"attempt" gorm:"column:attempt"`
	MaxAttempts int `json:"max_attempts" gorm:"column:max_attempts"`

	ScheduledAt time.Time  `json:"scheduled_at" gorm:"column:scheduled_at;index:idx_job_runs_status_sched,priority:2"`
	StartedAt   *time.Time `json:"started_at,omitempty" gorm:"column:started_at"`
	FinishedAt  *time.Time `json:"finished_at,omitempty" gorm:"column:finished_at"`
	DurationMS  int64      `json:"duration_ms" gorm:"column:duration_ms"`

	Progress        int             `json:"progress" gorm:"column:progress"`
	ProgressMessage string          `json:"progress_message,omitempty" gorm:"column:progress_message;size:255"`
	Result          json.RawMessage `json:"result,omitempty" gorm:"column:result;type:text"`
	Error           *RunError       `json:"error,omitempty" gorm:"column:error;serializer:json;type:text"`

	WorkerID string `json:"worker_id,omitempty" gorm:"column:worker_id;size:64"`

	// CaptureLogs overrides the job's log policy for this run only — what
	// "trigger it by hand and give me the full logs this once" sets.
	CaptureLogs *LogPolicy `json:"capture_logs,omitempty" gorm:"column:capture_logs"`

	CancelRequestedAt *time.Time `json:"cancel_requested_at,omitempty" gorm:"column:cancel_requested_at"`
	CanceledBy        string     `json:"canceled_by,omitempty" gorm:"column:canceled_by;size:191"`
	CancelReason      string     `json:"cancel_reason,omitempty" gorm:"column:cancel_reason;size:255"`

	// ReplayOf is the run this one was replayed from; RootID is the first run of
	// the chain (a replay of a replay still points at the original).
	ReplayOf string `json:"replay_of,omitempty" gorm:"column:replay_of;size:36"`
	RootID   string `json:"root_id,omitempty" gorm:"column:root_id;size:36"`

	CreatedAt time.Time `json:"created_at" gorm:"column:created_at"`
	UpdatedAt time.Time `json:"updated_at" gorm:"column:updated_at"`
}

JobRun is one execution of a job — the single record that answers "is it queued", "is it running", "did it work" and "who asked for it".

It is also a repository model (see the jobstore package), so services can query it with repository.New[core.JobRun](ctx).

func (JobRun) TableName

func (JobRun) TableName() string

TableName implements IModel.

type JobRunFilter

type JobRunFilter struct {
	JobName  string
	Statuses []RunStatus
	Trigger  Trigger
	Queue    string
	From     *time.Time
	To       *time.Time
	Page     *PageOptions
}

JobRunFilter narrows a run listing.

type JobRunner

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

JobRunner executes runs taken from the queue. It is the single path every run goes through — scheduled, manual, retried or replayed — which is why status, logs, concurrency and cancellation only had to be written once.

func NewJobRunner

func NewJobRunner(app *App, reg *JobRegistry, opts ...JobRunnerOption) *JobRunner

NewJobRunner builds a runner over reg. With no options it is fully functional out of the box: in-memory queue and store, in-process concurrency limits and no persisted logs.

func (*JobRunner) Cancel

func (r *JobRunner) Cancel(ctx context.Context, runID, by, reason string) IError

Cancel stops a run. A queued run never starts; a running one is asked to stop and its context is canceled — the handler has to cooperate (see ICronjobContext.Stopping).

func (*JobRunner) Logs

func (r *JobRunner) Logs(ctx context.Context, runID string, afterSeq int64, limit int) ([]JobLog, IError)

Logs returns persisted log lines after afterSeq. It is empty for runs whose policy did not persist anything — use TailLogs while a run is in flight.

func (*JobRunner) NextRun

func (r *JobRunner) NextRun(name string) (time.Time, bool)

NextRun is when a job fires next, and whether it is armed at all in this process.

False covers two cases that look identical from outside and are not: a manual-only job, and a scheduled job in a process whose role does not arm the cron — an API replica whose worker runs elsewhere. Both are correct silence. What it is worth for is the third case: a job that is supposed to be armed here and is not, which is where every "why has it not run?" starts.

Only a runner a Scheduler was built on can answer at all; the times come from gocron, so they exist once the scheduler is ticking.

func (*JobRunner) Pause

func (r *JobRunner) Pause(name string) IError

Pause stops a job being scheduled or triggered; Resume undoes it.

func (*JobRunner) Purge

func (r *JobRunner) Purge(ctx context.Context) (int64, IError)

Purge deletes runs and logs past their retention. Register it as a job to run it on a schedule.

func (*JobRunner) Registry

func (r *JobRunner) Registry() *JobRegistry

Registry returns the registry the runner executes.

func (*JobRunner) Replay

func (r *JobRunner) Replay(ctx context.Context, runID string, opts ...ReplayOptions) (*JobRun, IError)

Replay creates a new run from a finished one.

func (*JobRunner) Resume

func (r *JobRunner) Resume(name string) IError

func (*JobRunner) Run

func (r *JobRunner) Run(ctx context.Context, id string) (*JobRun, IError)

Run returns a single run.

func (*JobRunner) Runs

func (r *JobRunner) Runs(ctx context.Context, f JobRunFilter) (*Page[JobRun], IError)

Runs lists runs.

func (*JobRunner) Scheduled

func (r *JobRunner) Scheduled() bool

Scheduled reports whether a scheduler is feeding this runner, which is what tells "no next run because nothing is armed here" apart from "no next run because this job is manual".

func (*JobRunner) Start

func (r *JobRunner) Start()

Start launches the worker goroutines. It does not block.

func (*JobRunner) Stop

func (r *JobRunner) Stop(ctx context.Context) IError

Stop drains the runner: no new runs are picked up and in-flight ones are given until ctx expires to finish. Whatever is still running then is canceled and put back on the queue — never marked failed, because it never got to fail.

func (*JobRunner) Store

func (r *JobRunner) Store() IJobStore

Store returns the run store (for admin queries).

func (*JobRunner) TailLogs

func (r *JobRunner) TailLogs(runID string) (<-chan JobLog, func())

TailLogs streams the lines of a run *while it is running*, without touching the store — live debugging keeps working under LogOff. The returned function unsubscribes.

func (*JobRunner) Trigger

func (r *JobRunner) Trigger(ctx context.Context, name string, params any, opts ...TriggerOptions) (*JobRun, IError)

Trigger queues a run of name with params (any JSON-serialisable value, or nil for none) and returns the created run.

func (*JobRunner) TriggerAndWait

func (r *JobRunner) TriggerAndWait(ctx context.Context, name string, params any, opts ...TriggerOptions) (*JobRun, IError)

TriggerAndWait triggers a run and waits for it to finish, for the callers who need the outcome (an admin clicking "run now" and watching).

func (*JobRunner) Wait

func (r *JobRunner) Wait(ctx context.Context, runID string) (*JobRun, IError)

Wait blocks until the run reaches a terminal status or ctx is done.

type JobRunnerOption

type JobRunnerOption func(*JobRunner)

JobRunnerOption configures a runner.

func WithJobLimiter

func WithJobLimiter(l ILimiter) JobRunnerOption

WithJobLimiter sets the concurrency limiter (default: in-process).

func WithJobQueue

func WithJobQueue(q IJobQueue) JobRunnerOption

WithJobQueue sets the queue backend (default: in-memory).

func WithJobStore

func WithJobStore(s IJobStore) JobRunnerOption

WithJobStore sets the store backend (default: in-memory).

func WithLogLimits

func WithLogLimits(l LogLimits) JobRunnerOption

WithLogLimits bounds what a single run may persist.

func WithLogPolicy

func WithLogPolicy(p LogPolicy) JobRunnerOption

WithLogPolicy sets the default log policy for every job (default: LogOff, because persisted logs are the most expensive part of the system).

func WithQueueLimit

func WithQueueLimit(queue string, limit int) JobRunnerOption

WithQueueLimit caps how many runs of a whole queue may execute at once.

func WithQueues

func WithQueues(names ...string) JobRunnerOption

WithQueues restricts the runner to the named queues (default: "default").

func WithSlotBackoff

func WithSlotBackoff(d time.Duration) JobRunnerOption

WithSlotBackoff sets how long a run waits before retrying for a concurrency slot under ConcurrencyEnqueue.

func WithWorkerID

func WithWorkerID(id string) JobRunnerOption

WithWorkerID labels the runs this process executes.

func WithWorkers

func WithWorkers(n int) JobRunnerOption

WithWorkers sets how many runs this process executes at once.

type LLMCapabilities

type LLMCapabilities struct {
	Streaming        bool
	StructuredOutput bool
	Reasoning        bool
	PromptCaching    bool
	TokenCounting    bool
	Tools            bool
	// Vision reports whether this driver can *send* attachments to this
	// provider — not whether the configured model can read them. Those are
	// different questions and only the first has an answer the driver knows:
	// vision support varies by model, not by provider, and a model that cannot
	// see is rejected by the provider with its own error.
	//
	// What it guarantees is the thing that matters: with Vision true an image
	// is delivered or reported, never quietly dropped.
	Vision bool
}

LLMCapabilities is what a model can actually do. Drivers report it so a caller can branch before sending rather than discovering the answer as an error — and so the disabled model can report nothing without lying.

type LLMFinishReason

type LLMFinishReason string

LLMFinishReason is why generation stopped, normalised across providers.

const (
	LLMFinishStop          LLMFinishReason = "stop"
	LLMFinishLength        LLMFinishReason = "length"
	LLMFinishContentFilter LLMFinishReason = "content_filter"
	LLMFinishToolUse       LLMFinishReason = "tool_use"
	LLMFinishError         LLMFinishReason = "error"
	LLMFinishOther         LLMFinishReason = "other"
)

type LLMMessage

type LLMMessage struct {
	Role LLMRole
	Text string
	// Parts are attachments — images, documents. Empty for an ordinary text
	// turn, which is what keeps every existing call site working unchanged.
	Parts []LLMPart
}

LLMMessage is one turn of the conversation.

func LLMAssistant

func LLMAssistant(text string) LLMMessage

LLMAssistant returns an assistant turn — for replaying history, not for prefilling a reply. Several current models reject a conversation that ends on an assistant turn.

func LLMUser

func LLMUser(text string) LLMMessage

LLMUser returns a user turn.

func (LLMMessage) With

func (m LLMMessage) With(parts ...LLMPart) LLMMessage

With attaches parts to a message:

core.LLMUser("ยอดรวมเท่าไหร่").With(core.LLMImage(scan, "image/jpeg"))

The text still matters — a model given an image and no instruction describes it, which is rarely what the caller wanted.

type LLMPart

type LLMPart struct {
	Type LLMPartType
	// Data is the raw bytes. Drivers base64-encode it, which inflates it by a
	// third on the wire — see LLMMaxAttachmentBytes.
	Data []byte
	// URL is a link the provider fetches, or a data: URI. Mutually exclusive
	// with Data.
	URL string
	// MediaType is required with Data ("image/jpeg", "application/pdf"). It
	// cannot be guessed from bytes reliably enough to be worth guessing: a
	// wrong one is rejected by the provider with an error about the image, not
	// about the media type.
	MediaType string
	// Filename is shown to the model for a file. Some providers use it as a
	// hint about the content, so a name like "invoice-2026-08.pdf" is worth
	// more than "upload".
	Filename string
	// Detail asks for a resolution tier on providers that offer one:
	// "low", "high" or "auto". Empty leaves the provider's default. "low" costs
	// far fewer tokens and is enough for a layout question but not for reading
	// small print.
	Detail string
}

LLMPart is something attached to a message that is not text.

Exactly one of Data or URL is set. Data is the bytes themselves — the usual case, since a scan or a screenshot is already in memory; URL points at something the provider fetches, which only some of them will do.

func LLMFile

func LLMFile(data []byte, mediaType, filename string) LLMPart

LLMFile attaches a document. filename is optional but worth setting.

func LLMImage

func LLMImage(data []byte, mediaType string) LLMPart

LLMImage attaches an image from bytes.

func LLMImageURL

func LLMImageURL(url string) LLMPart

LLMImageURL attaches an image the provider fetches itself. Not every provider will — the ones that do not return LLM_UNSUPPORTED rather than sending a message with a hole where the picture should be.

type LLMPartType

type LLMPartType string

LLMPartType is the kind of attachment carried alongside a message's text.

const (
	LLMPartImage LLMPartType = "image"
	// LLMPartFile is a document — a PDF, a spreadsheet, a text file. Support
	// varies far more than images do: some providers read PDFs natively, others
	// reject them, and a driver that cannot send one says so rather than
	// dropping it.
	LLMPartFile LLMPartType = "file"
)

type LLMReasoning

type LLMReasoning string

LLMReasoning is how much thinking to spend, as a level rather than a token budget. Providers express this differently — an effort enum, a token budget, a boolean — and a level is the only form all of them can honour.

const (
	// LLMReasoningDefault leaves the provider's own default in place. It is the
	// zero value, so a request that says nothing about reasoning gets whatever
	// the model does normally.
	LLMReasoningDefault LLMReasoning = ""
	LLMReasoningOff     LLMReasoning = "off"
	LLMReasoningLow     LLMReasoning = "low"
	LLMReasoningMedium  LLMReasoning = "medium"
	LLMReasoningHigh    LLMReasoning = "high"
	LLMReasoningMax     LLMReasoning = "max"
)

type LLMRequest

type LLMRequest struct {
	// Model overrides the configured default. It is the provider's own model
	// id — routing a friendly name to one belongs in configuration, not here.
	Model string
	// System is the system prompt. Keep it byte-stable across requests: it sits
	// at the front of the prompt, so anything varying in it (a timestamp, a
	// request id) defeats prompt caching for everything after it.
	System string
	// Messages is the conversation, oldest first. Must not be empty.
	Messages []LLMMessage
	// MaxTokens caps the reply. 0 uses the configured default.
	MaxTokens int
	// Temperature is a pointer because 0 is a meaningful value and several
	// current models reject the parameter entirely — nil means "do not send it".
	Temperature   *float64
	StopSequences []string
	// Reasoning is how hard to think. See LLMReasoning.
	Reasoning LLMReasoning
	// Schema constrains the reply to JSON. nil means free text.
	Schema *LLMSchema
	// CacheSystem marks the system prompt as a prompt-cache prefix. It is a
	// hint: providers that cache automatically ignore it, and drivers that
	// cannot cache ignore it too, because a missed cache costs money but never
	// changes the answer.
	CacheSystem bool
	// Tools the model may call. With none, the model can only answer.
	Tools []LLMTool
	// MaxSteps bounds the tool loop: one model turn plus its tool results is a
	// step. 0 and 1 both mean a single turn, so a request that lists tools but
	// forgets MaxSteps gets the calls back rather than silently looping.
	//
	// It exists because a loop with no ceiling is a loop that can bill without
	// end — a model that keeps calling a tool that keeps failing will happily
	// do so until something stops it.
	MaxSteps int
	// Approve gates every call before it runs. nil allows them all, which is
	// only appropriate when every tool is read-only.
	Approve LLMToolApprover
	// ProviderOptions carries provider-specific parameters straight through,
	// untranslated. It is the escape hatch that keeps this struct from having
	// to grow a field for every vendor's newest flag — at the cost of no
	// compile-time checking, so prefer a typed field when one exists.
	ProviderOptions map[string]any
}

LLMRequest is one generation. Every field beyond Messages is optional; a driver that cannot honour a field it was given returns ErrLLMUnsupported rather than dropping it, so the request never runs as something other than what the caller asked for.

func LLMCalls

func LLMCalls(l ILLM) []LLMRequest

LLMCalls returns the requests a memory model has recorded, in order. It returns nil for any other model.

func (LLMRequest) RunTool

func (r LLMRequest) RunTool(ctx context.Context, call LLMToolCall) LLMToolResult

RunTool executes one call against the request's tools, applying Approve first. Drivers use it so the gate, the not-found error and the panic guard behave identically no matter which provider drove the loop.

func (LLMRequest) Validate

func (r LLMRequest) Validate() IError

Validate checks the request the way every driver must, before anything is sent.

It is exported because drivers live in other packages and each one needs the same answer: a caller's mistake has to read identically whichever provider is configured, and a second copy of these rules is a second thing to forget when one of them grows — which is exactly what happened the first time attachments were added.

type LLMResponse

type LLMResponse struct {
	Text         string
	Model        string
	Provider     string
	FinishReason LLMFinishReason
	Usage        LLMUsage
	// Steps is how many model turns it took. 1 means the model answered
	// directly; more means it called tools along the way.
	Steps int
	// ToolCalls is every call the model made, in order — the audit trail of
	// what a loop actually did, which is the thing you want when it did
	// something surprising.
	ToolCalls []LLMToolCall
	// Sources is what a grounded answer was based on. It is only populated by
	// providers that ground — a Google Search or URL-context tool, a provider's
	// own citations — and is the part of grounding that has to reach the user:
	// an answer about current events with no link to what it read is exactly as
	// trustworthy as one the model invented.
	Sources []LLMSource
	// Raw is the driver's own response value, for reading something this struct
	// does not carry. Type-assert it to the driver's type; it may be nil.
	Raw any
}

LLMResponse is one completed generation.

type LLMRole

type LLMRole string

LLMRole identifies who authored a message. There is no system role — the system prompt is its own field on LLMRequest, because providers disagree on where it belongs (a leading message, a top-level field, a per-turn block) and a driver can only place it correctly if it knows which one it is.

const (
	LLMRoleUser      LLMRole = "user"
	LLMRoleAssistant LLMRole = "assistant"
)

type LLMSchema

type LLMSchema struct {
	Name   string
	Schema map[string]any
	// Strict asks the provider to guarantee the shape rather than merely
	// request it. Drivers that cannot enforce it must fail rather than silently
	// downgrade — a schema that was only a suggestion is the failure mode this
	// whole type exists to prevent.
	Strict bool
}

LLMSchema constrains the reply to a JSON schema. Schema is the schema itself, as the provider expects it; Name is what some providers require alongside it.

type LLMSource

type LLMSource struct {
	// ID is the provider's own identifier, empty for providers that issue none.
	ID string
	// Type is the kind of source — "url" for a search result, "document" for a
	// retrieved file.
	Type  string
	URL   string
	Title string
}

LLMSource is one thing a grounded answer cited.

type LLMStream

type LLMStream interface {
	// Next advances to the next delta, returning false at the end of the
	// stream or on error.
	Next() bool
	// Text is the delta Next just advanced to — a fragment, not the whole
	// reply so far.
	Text() string
	// Response is the accumulated result. It is only complete once Next has
	// returned false.
	Response() LLMResponse
	// Err is the error that ended the stream, or nil if it ended normally.
	Err() IError
	// Close releases the underlying connection. Safe to call more than once,
	// and safe to call before the stream is drained.
	Close() IError
}

LLMStream is a generation being received. It is an iterator rather than a channel so that ending early is an ordinary Close rather than a leaked goroutine, and so the terminal error has one place to live:

s, err := core.LLM(ctx).Stream(req)
if err != nil { return err }
defer s.Close()
for s.Next() {
    fmt.Print(s.Text())
}
if err := s.Err(); err != nil { return err }
usage := s.Response().Usage

type LLMTool

type LLMTool struct {
	Name string
	// Description is what the model reads to decide whether to call it. Say
	// *when* to use it, not only what it does: "call this when the user asks
	// about an order's status" beats "looks up orders".
	Description string
	// Schema is the JSON Schema of the input, as a closed object.
	Schema map[string]any
	// Execute runs the tool. Both its result and its error text are sent back
	// to the model, so neither may carry a credential, an internal path, or
	// anything else that should not leave the process.
	//
	// Required for an ordinary tool, and necessarily absent for a
	// provider-defined one.
	Execute func(ctx context.Context, input json.RawMessage) (string, IError)
	// ProviderType marks this as a tool the provider implements, named the way
	// that provider names it ("google.google_search"). The framework does not
	// interpret it: a driver either recognises it or rejects the request, which
	// is what keeps an option meant for one provider from being quietly ignored
	// by another.
	ProviderType string
	// ProviderOptions configures a provider-defined tool — a time-range filter
	// on a search, a display size for computer use. Ignored for an ordinary
	// tool.
	ProviderOptions map[string]any
}

LLMTool is a function the model may call during a generation.

Build one with llm.Tool[In] rather than by hand — it derives Schema from the input type, which is the part that is tedious to write and easy to get subtly wrong.

A tool with ProviderType set is the other kind: something the provider runs itself, on its own side of the wire — Google Search grounding, URL fetching, a sandboxed interpreter. It has no Execute because there is nothing here to run; build one with the driver's constructor (goai.GoogleSearch()) rather than by spelling the type out.

func (LLMTool) IsProviderDefined

func (t LLMTool) IsProviderDefined() bool

IsProviderDefined reports whether the provider runs this tool itself.

type LLMToolApprover

type LLMToolApprover func(ctx context.Context, call LLMToolCall) IError

LLMToolApprover decides whether a call the model asked for may run.

Returning an error denies it: the error's message goes back to the model as the tool result, so the model can explain itself or try another route, and the generation continues rather than failing.

This is the reason tool use belongs in the framework rather than being left to each service — a loop that can write to a database needs one place where the decision is made, logged and testable:

Approve: func(ctx context.Context, call core.LLMToolCall) core.IError {
    if call.Name == "refund_order" {
        return core.New(403, "NEEDS_HUMAN", "refunds require an operator")
    }
    return nil
}

type LLMToolCall

type LLMToolCall struct {
	// ID is the provider's own identifier for the call, used to match the
	// result back. Empty for providers that do not issue one.
	ID   string
	Name string
	// Input is the arguments as the model produced them. It is raw JSON rather
	// than a map so a tool can unmarshal straight into its own type.
	Input json.RawMessage
	// Outcome is what happened once the call was executed — empty on a call the
	// model merely asked for, because the loop ran out of steps before it ran.
	Outcome LLMToolOutcome
	// Output is what went back to the model: the tool's own result, or the text
	// explaining a denial or a failure.
	//
	// It completes the audit trail — "the model asked to refund an order",
	// "the refund ran" and "the refund returned this" are three different
	// facts, and a record holding only the first two cannot answer what the
	// model was actually told. Empty for a call that never ran.
	//
	// Like the arguments, it is application data and can carry anything the
	// tool reads, so it is only written to the log when AI_LOG_COMPLETION says
	// so.
	Output string
}

LLMToolCall is one invocation the model asked for.

func MemoryToolCall

func MemoryToolCall(name, inputJSON string) LLMToolCall

MemoryToolCall is a shorthand for scripting one call.

core.QueueLLMReply(m, core.MemoryLLMReply{
    ToolCalls: []core.LLMToolCall{core.MemoryToolCall("get_weather", `{"city":"Bangkok"}`)},
})

type LLMToolOutcome

type LLMToolOutcome string

LLMToolOutcome is what happened to one call. It exists so the audit trail records the decision and not only the attempt — "the model asked to refund an order" and "the model refunded an order" are different events, and a log that cannot tell them apart is worse than no log.

const (
	LLMToolRan     LLMToolOutcome = "ran"
	LLMToolDenied  LLMToolOutcome = "denied"
	LLMToolFailed  LLMToolOutcome = "failed"
	LLMToolUnknown LLMToolOutcome = "unknown_tool"
)

type LLMToolResult

type LLMToolResult struct {
	// Output is what goes back to the model — including when it describes a
	// refusal or a failure, because a model told why its call did not run can
	// adapt, while one told nothing repeats itself until MaxSteps runs out.
	Output  string
	Outcome LLMToolOutcome
	// Err is the failure or the refusal, for the log. It never reaches the
	// model as an error — only its message does, inside Output.
	Err IError
}

LLMToolResult is one executed call.

type LLMUsage

type LLMUsage struct {
	InputTokens       int
	OutputTokens      int
	CachedInputTokens int
	ReasoningTokens   int
}

LLMUsage is what the call consumed. CachedInputTokens and ReasoningTokens are reported separately because they are billed differently from ordinary input and output — folding them in would make a cost report wrong in the direction that looks fine.

func (LLMUsage) Total

func (u LLMUsage) Total() int

Total is every token the call touched.

type Level

type Level = sentry.Level

Level is the severity of a captured event.

type LimiterOption

type LimiterOption func(*limiterConfig)

LimiterOption configures a Redis-backed limiter.

func WithLimiterCache

func WithLimiterCache(name string) LimiterOption

WithLimiterCache picks a named cache registered on the App ("default" when not set), for services that keep their coordination redis apart from their cache.

func WithLimiterLease

func WithLimiterLease(d time.Duration) LimiterOption

WithLimiterLease overrides how long a slot is held without a heartbeat.

func WithLimiterLogger

func WithLimiterLogger(l ILogger) LimiterOption

WithLimiterLogger overrides the logger the limiter reports redis trouble on.

func WithLimiterPrefix

func WithLimiterPrefix(prefix string) LimiterOption

WithLimiterPrefix replaces the whole key namespace — cache prefix included. Give two services the same prefix and they share one limit; that is the only way to make a job that runs in both count as one.

type LogEntry

type LogEntry struct {
	At      time.Time `json:"at"`
	Level   string    `json:"level"`
	Message string    `json:"message"`
	// Source is the "file.go:12" the line was written at, empty when LOG_SOURCE
	// is off.
	Source string         `json:"source,omitempty"`
	Attrs  map[string]any `json:"attrs,omitempty"`
}

LogEntry is one log line handed to an observer, flattened out of slog's Record so a reader does not have to know how slog works — and, more importantly, so it is safe to keep: a slog.Record's attributes may not be iterated twice or held past the Handle call, and an observer that stores one would be reading memory the logger has moved on from.

type LogLimits

type LogLimits struct {
	MaxLines int    // 0 = DefaultLogMaxLines
	MaxBytes int    // 0 = DefaultLogMaxBytes
	MinLevel string // "debug" (default) | "info" | "warn" | "error"
	// TailLines is how many trailing lines are attached to JobRun.Error when a
	// run fails, even under LogOff. 0 = DefaultLogTailLines.
	TailLines int
}

LogLimits bounds what a single run may persist.

type LogPolicy

type LogPolicy uint8

LogPolicy controls whether a run's logs are persisted to the store. Logs are by far the largest consumer of storage (one row per line, per run), so the default is off — see the notes on JobDef.Logs.

const (
	// LogOff never writes logs to the store. Logs still go to the application
	// logger (stdout), live tailing still works while the run is in flight, and
	// the tail of the buffer is still attached to JobRun.Error on failure.
	LogOff LogPolicy = iota
	// LogOnFailure buffers logs in memory and flushes them to the store only if
	// the run does not succeed. Successful runs cost nothing.
	LogOnFailure
	// LogAlways persists every line of every run. Reserve it for important,
	// infrequent jobs.
	LogAlways
)

func LogPolicyPtr

func LogPolicyPtr(p LogPolicy) *LogPolicy

LogPolicyPtr is a helper for the pointer fields on JobDef/TriggerOptions.

type LogTapFunc

type LogTapFunc func(ctx context.Context, entry LogEntry)

LogTapFunc is called for every line the App's logger writes, with the context the line was written under — which is what lets an observer attribute it to a request (see RequestID).

It runs inline, on the goroutine that logged, so it must be quick and must not log anything itself: a tap that writes a line writes it through the same logger and never returns.

type MQConsumerOption

type MQConsumerOption func(*mqConsumerOptions)

MQConsumerOption tunes a consumer.

func WithMQConcurrency

func WithMQConcurrency(n int) MQConsumerOption

WithMQConcurrency allows n handlers to run at once. The default is 1, which keeps a queue's messages in order; raising it trades that order for throughput, so raise it only when the handlers are independent.

func WithMQConsumerTag

func WithMQConsumerTag(tag string) MQConsumerOption

WithMQConsumerTag names this consumer on the broker, which is what the management UI shows. Defaults to the service name.

func WithMQHandlerTimeout

func WithMQHandlerTimeout(d time.Duration) MQConsumerOption

WithMQHandlerTimeout bounds one handler (default DefaultMQHandlerTimeout). A handler that overruns has its context cancelled, and its message is requeued rather than lost.

func WithMQPrefetch

func WithMQPrefetch(n int) MQConsumerOption

WithMQPrefetch sets how many unacknowledged messages the broker may hand this consumer at once (default DefaultMQPrefetch).

func WithMQReconnectDelay

func WithMQReconnectDelay(d time.Duration) MQConsumerOption

WithMQReconnectDelay sets how long to wait before redialling (default DefaultMQReconnectDelay).

type MQHandler

type MQHandler func(ctx IMQContext, d *Delivery) error

MQHandler handles one delivery. The context is a full IMQContext — logger, database, cache, Sentry, and the delivery itself — built for that message and cancelled when the handler's timeout runs out.

Returning nil acknowledges the message. Returning an error rejects it: it goes to the queue's dead-letter exchange, or is dropped when the queue has none. Wrap the error in Requeue to ask for redelivery instead.

type MQOption

type MQOption func(*mqConfig)

MQOption tunes a publisher at construction.

func WithMQChannels

func WithMQChannels(n int) MQOption

WithMQChannels sets how many publishes may be in flight at once. Raise it for a service that publishes from many requests at once; every channel is a small amount of state on the broker, and brokers cap them (channel_max, 2047 by default).

func WithMQPublishTimeout

func WithMQPublishTimeout(d time.Duration) MQOption

WithMQPublishTimeout bounds one publish including the wait for the broker's confirmation.

type MailTemplateOptions

type MailTemplateOptions struct {
	// Root is a subdirectory of the FS to read from, so an embed.FS rooted at
	// the module can still be addressed by template name alone.
	Root string
	// Funcs are the functions templates may call.
	Funcs map[string]any
}

MailTemplateOptions tunes template parsing.

type MailTemplates

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

MailTemplates renders the bodies of an email. It keeps an html/template set for HTML bodies and a text/template set for plain ones, so an HTML body escapes what it interpolates — a display name containing "<" must not be able to rewrite the message around it — and a plain body does not get mangled by escaping it does not need.

func NewMailTemplateSet

func NewMailTemplateSet(funcs ...map[string]any) *MailTemplates

NewMailTemplateSet builds an empty set, for bodies that live in code or come from a database rather than from files.

func (*MailTemplates) Add

func (t *MailTemplates) Add(name, html, text string) IError

Add registers one template. Either body may be empty.

func (*MailTemplates) Names

func (t *MailTemplates) Names() []string

Names lists every template that can be rendered, sorted — for a startup check that the ones a service sends actually parsed.

func (*MailTemplates) Render

func (t *MailTemplates) Render(name string, data any) (string, string, IError)

Render executes both bodies of a template. A template with only one body returns "" for the other; a name with neither is an error, because a message with no body is never what was meant.

type MailerOption

type MailerOption func(*mailerConfig)

MailerOption tunes a mailer at construction.

func WithMailAuth

func WithMailAuth(a mail.SMTPAuthType) MailerOption

WithMailAuth overrides EMAIL_AUTH.

func WithMailClientOptions

func WithMailClientOptions(opts ...mail.Option) MailerOption

WithMailClientOptions passes go-mail options through, for anything this package does not name.

func WithMailHELO

func WithMailHELO(name string) MailerOption

WithMailHELO sets the HELO/EHLO name. Some providers refuse a name that does not resolve.

func WithMailTLSConfig

func WithMailTLSConfig(t *tls.Config) MailerOption

WithMailTLSConfig sets the TLS configuration — a private CA, a client certificate.

func WithMailTLSPolicy

func WithMailTLSPolicy(p mail.TLSPolicy) MailerOption

WithMailTLSPolicy overrides EMAIL_TLS_POLICY.

func WithMailTemplates

func WithMailTemplates(t *MailTemplates) MailerOption

WithMailTemplates registers the templates SendTemplate renders.

func WithMailTimeout

func WithMailTimeout(d time.Duration) MailerOption

WithMailTimeout bounds one delivery (default DefaultMailTimeout).

type MemoryLLMReply

type MemoryLLMReply struct {
	Text         string
	Usage        LLMUsage
	FinishReason LLMFinishReason
	// ToolCalls makes the model ask for tools instead of answering. The memory
	// model runs them — through the same approval gate a real driver uses — and
	// then consumes the next scripted reply as the turn that follows.
	//
	// That is what makes a tool handler testable: the decision to call is the
	// model's job, and scripting it is the only way to reach the handler
	// without a provider.
	ToolCalls []LLMToolCall
	// Sources scripts a grounded answer's citations. Without them a service that
	// renders sources — which the grounding services require it to — could only
	// be tested against a real provider, which is the same as not being tested.
	Sources []LLMSource
	// Err makes the call fail. Use it to exercise the path a provider outage
	// takes without waiting for one.
	Err IError
}

MemoryLLMReply is one scripted reply for a memory model. Only the fields a test cares about need setting: an empty Text with a nil Err still produces a valid response, which is what a test asserting only on the request wants.

type MetricOption

type MetricOption func(*metricOptions)

MetricOption tunes a single measurement.

func MetricAttr

func MetricAttr(key string, value any) MetricOption

MetricAttr adds one dimension to break the metric down by. Keep the values bounded — a customer id makes as many series as you have customers.

func MetricAttrs

func MetricAttrs(attrs map[string]any) MetricOption

MetricAttrs adds several dimensions at once.

func MetricUnit

func MetricUnit(unit string) MetricOption

MetricUnit states what the value is measured in, so Sentry renders "250ms" instead of "250".

type Mode

type Mode uint8

Mode identifies the entry point a context serves, mirroring v1's ContextType.

const (
	ModeHTTP Mode = iota
	ModeCron
	ModeMQ
	ModeTest
)

func (Mode) String

func (m Mode) String() string

String makes Mode readable in tags and logs.

type ModuleReport

type ModuleReport struct {
	Name string `json:"name"`
	// Declares is the optional module interfaces this module implements —
	// "routes", "jobs", "cron", "consumers", "health", "lifecycle" — fixed at
	// assembly time, because it is a property of the type rather than of the
	// mount.
	//
	// It is what gives every other field here a denominator. A module with no
	// routes and a module whose routes this role never mounted are the same
	// empty list, and only the second is a problem; the same goes for Started,
	// which is false both for a module that has no background work and for one
	// whose Start never ran.
	Declares []string `json:"declares,omitempty"`
	// Started says background work is running — meaningful only when Declares
	// contains "lifecycle".
	Started bool `json:"started"`
	// Routes are "METHOD /path", for the routes registered through the
	// framework's own helpers. See Server.HandlerNames for the exception.
	Routes []string `json:"routes,omitempty"`
	// Jobs are the job names registered without a schedule.
	Jobs []string `json:"jobs,omitempty"`
	// Cron are the job names armed on a schedule.
	Cron []string `json:"cron,omitempty"`
	// Queues are the queue names consumed.
	Queues []string `json:"queues,omitempty"`
	// Health are the check names, already prefixed with the module's name.
	Health []string `json:"health,omitempty"`
}

ModuleReport is what one module actually registered, captured as it was mounted.

It answers the question that makes a module system worth having: not "what does this module claim to do" but "what did it attach to this process" — the cron that was never armed because this role has no scheduler is visible here and nowhere else.

type ModuleSet

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

ModuleSet is the assembled modules of a service, and the only thing that mounts them.

Safe for concurrent use: mounting happens at boot on one goroutine, but Report is read by the devtools handler while the process serves.

func (*ModuleSet) HealthChecks

func (s *ModuleSet) HealthChecks() []HealthCheck

HealthChecks is every module's checks, each one named "<module>.<check>".

Pass them to the probe at the composition root:

core.RegisterHealthRoutes(e, core.HealthOptions{Checks: mods.HealthChecks()})

They are deliberately not stored on the App: the probe would then depend on having been registered after the modules, and a probe reporting fewer checks than the service has says nothing about the fact that it is incomplete.

func (*ModuleSet) MountConsumers

func (s *ModuleSet) MountConsumers(c IMQConsumer)

MountConsumers registers every module's queue consumers on c. Mounting the same consumer twice is a no-op.

func (*ModuleSet) MountCron

func (s *ModuleSet) MountCron(sc *Scheduler) IError

MountCron arms every module's scheduled jobs on sc. Mounting the same scheduler twice is a no-op.

func (*ModuleSet) MountHTTP

func (s *ModuleSet) MountHTTP(e *Server)

MountHTTP registers every module's routes on e.

Mounting the same server twice is a no-op. That is not defensive coding: a service registers routes in its own NewAPI (which is what its tests call, and they never build a Runner) and then hands the same set to RunModules, so the second mount is the normal case rather than a mistake. A different server — a second listener, a test's own — mounts as usual.

func (*ModuleSet) MountJobs

func (s *ModuleSet) MountJobs(reg *JobRegistry) IError

MountJobs registers every module's job definitions on reg. Mounting the same registry twice is a no-op.

func (*ModuleSet) Names

func (s *ModuleSet) Names() []string

Names is every module's name, in the order they were declared.

func (*ModuleSet) Report

func (s *ModuleSet) Report() []ModuleReport

Report is what each module registered, ordered by declaration.

func (*ModuleSet) Start

func (s *ModuleSet) Start(app *App) IError

Start starts every module that has background work of its own, in declaration order. The first failure stops the rest: a half-started service is worse than one that refuses to boot, because only the second is noticed at deploy time.

func (*ModuleSet) Stop

func (s *ModuleSet) Stop(ctx context.Context) IError

Stop stops the modules that started, in reverse declaration order — the mirror of Start, so a module that depends on one declared before it is gone before that one is.

Every module is asked to stop even if one fails; the first error is returned.

type MongoAggregateOptions

type MongoAggregateOptions struct {
	// AllowDiskUse lets $group and $sort spill to disk past the 100MB in-memory
	// limit. It is the difference between a report that runs and one that fails
	// with "Sort exceeded memory limit" the first time the data gets big.
	AllowDiskUse bool
	// MaxTime bounds the pipeline on the server.
	MaxTime time.Duration
	// BatchSize tunes how many documents come back per round trip.
	BatchSize int32
	// Hint forces an index for the initial $match.
	Hint any
	// Let declares variables the pipeline reads with "$$name".
	Let any
	// Collation decides how strings compare and group.
	Collation *options.Collation
	// Comment shows up in the profiler and in currentOp, which is how a
	// long-running pipeline is identified in production.
	Comment string
}

MongoAggregateOptions shapes a pipeline run.

type MongoBulkResult

type MongoBulkResult struct {
	Inserted    int64
	Matched     int64
	Modified    int64
	Deleted     int64
	Upserted    int64
	UpsertedIDs map[int64]string
}

MongoBulkResult is the tally of a BulkWrite.

type MongoFindModifyOptions

type MongoFindModifyOptions struct {
	// Upsert inserts when nothing matches (FindOneAndUpdate/Replace only).
	Upsert bool
	// ReturnNew decodes the document as it is *after* the change. The default
	// is before, which is Mongo's, and is what you want when the old value is
	// the thing being claimed.
	ReturnNew bool
	// Sort decides which document is modified when several match — the ordering
	// that turns this into a queue pop.
	Sort         []string
	Projection   any
	ArrayFilters []any
	Collation    *options.Collation
	MaxTime      time.Duration
}

MongoFindModifyOptions shapes an atomic find-and-modify.

type MongoFindOptions

type MongoFindOptions struct {
	Sort  []string
	Limit int64
	Skip  int64
	// Projection is passed to the driver as-is (bson.M{"password": 0}), so the
	// full projection language is available.
	Projection any
	// Hint forces an index ("email_1", or bson.D of the keys) when the planner
	// picks the wrong one.
	Hint any
	// Collation decides how strings compare — the way to get a case- or
	// accent-insensitive query instead of a regex that cannot use an index.
	Collation *options.Collation
	// MaxTime bounds the query on the *server*, so a slow one is killed there
	// rather than only abandoned here.
	MaxTime time.Duration
	// BatchSize tunes how many documents come back per round trip.
	BatchSize int32
}

MongoFindOptions shapes a read. Every field is optional.

Sort names a field per entry, "-" first for descending ("-created_at"), which is the same shape PageOptions.OrderBy uses.

type MongoIndex

type MongoIndex struct {
	// Keys names a field per entry, "-" first for descending. A compound index
	// is several entries, in order. A non-numeric direction is given as
	// "field:text" / "field:2dsphere" / "field:hashed".
	Keys   []string
	Unique bool
	Sparse bool
	// TTL expires documents this long after the (single, date-typed) key.
	TTL time.Duration
	// Name is generated from the keys when empty.
	Name string
	// Partial restricts which documents are indexed (bson.M{"deleted_at": nil}).
	Partial any
	// Collation decides how the indexed strings compare; a query only uses the
	// index when its collation matches.
	Collation *options.Collation
	// Weights tunes a text index's field importance.
	Weights any
	// Background is accepted and ignored by MongoDB 4.2+, which always builds
	// this way. It is here so an index definition ported from an older service
	// still compiles.
	Background bool
}

MongoIndex describes an index to create at startup.

type MongoLogLevel

type MongoLogLevel int

MongoLogLevel decides how much of the traffic to Mongo is logged. It mirrors the SQL side: failures always, slow commands at Warn, everything at Info.

const (
	// MongoLogSilent logs nothing at all.
	MongoLogSilent MongoLogLevel = iota
	// MongoLogError logs failed commands.
	MongoLogError
	// MongoLogWarn logs failures and slow commands. The default.
	MongoLogWarn
	// MongoLogInfo logs every command.
	MongoLogInfo
)

type MongoOption

type MongoOption func(*mongoOptions)

MongoOption configures a Mongo connection.

func WithMongoLogLevel

func WithMongoLogLevel(level MongoLogLevel) MongoOption

WithMongoLogLevel overrides how much of the traffic to Mongo is logged, independently of LOG_LEVEL: MongoLogInfo logs every command, MongoLogWarn only slow ones and failures, MongoLogSilent nothing.

m, _ := core.NewMongoDB(env, core.WithMongoLogLevel(core.MongoLogInfo))

func WithMongoLogger

func WithMongoLogger(l ILogger) MongoOption

WithMongoLogger sends command logs to a specific logger instead of one built from configuration.

func WithMongoMonitor

func WithMongoMonitor(monitor *event.CommandMonitor) MongoOption

WithMongoMonitor replaces the command monitor entirely — for tracing, metrics, or a logger of your own. Pass nil to record nothing.

func WithMongoPoolMonitor

func WithMongoPoolMonitor(monitor *event.PoolMonitor) MongoOption

WithMongoPoolMonitor replaces the connection-pool monitor. Pass nil to give up the only warning there is that the pool is exhausted.

func WithMongoServerMonitor

func WithMongoServerMonitor(monitor *event.ServerMonitor) MongoOption

WithMongoServerMonitor replaces the topology monitor. Pass nil to record nothing about members going away or the primary moving.

func WithMongoSlowQuery

func WithMongoSlowQuery(d time.Duration) MongoOption

WithMongoSlowQuery sets the duration above which a command is logged as slow (default 200ms).

type MongoUpdateOptions

type MongoUpdateOptions struct {
	// Upsert inserts the document when the filter matches nothing.
	Upsert bool
	// ArrayFilters targets the elements a positional "$[name]" update applies
	// to (bson.A{bson.M{"name.score": bson.M{"$lt": 50}}}).
	ArrayFilters []any
	// Hint forces an index for the filter.
	Hint any
	// Collation decides how the filter compares strings.
	Collation *options.Collation
}

MongoUpdateOptions shapes a write.

type MongoUpdateResult

type MongoUpdateResult struct {
	Matched    int64
	Modified   int64
	Upserted   int64
	UpsertedID string
}

MongoUpdateResult is what a write actually did. Matched being zero is how a caller tells "no such document" from "nothing needed changing" — a distinction the previous IError-only signature threw away.

type Option

type Option func(*App)

Option configures an App at construction.

func WithCache

func WithCache(name string, c ICache) Option

WithCache registers a cache under name ("default" for the primary).

func WithChat

func WithChat(name string, c IChat) Option

WithChat registers a chat provider under name ("default" for the primary). Build one with a driver (chat/slack.New(env)) at startup, or pass NewMemoryChat() in a test to assert on what a service would have posted.

It is named like WithSQL and WithCache rather than like WithMailer because a service routinely posts to more than one place — alerts to an internal Slack, replies to customers on LINE — and those are different providers, not one provider with two destinations.

func WithEmbedder

func WithEmbedder(e IEmbedder) Option

WithEmbedder registers the embedding model. It is separate from WithLLM because the two are separate models — often from different vendors, since the provider a service generates with may not offer embeddings at all.

func WithLLM

func WithLLM(l ILLM) Option

WithLLM registers the language model. Build one with a driver (llm/goai.New(env)) at startup, or pass NewMemoryLLM(...) in a test to assert on what a service would have asked a model, without a network call or a key.

func WithLogTap

func WithLogTap(tap LogTapFunc) Option

WithLogTap installs an observer over the App's logger.

It exists for the tools that have to see the framework's own output as structured events rather than as text on stdout — the devtools request trace is the one in the tree. Reporting to a log aggregator is not what this is for: that is a slog handler, configured with WithLogger.

trace := devtools.NewTrace(devtools.TraceOptions{})
app, err := core.NewApp(env, core.WithLogTap(trace.Log), …)

A tap only sees what is actually logged: a line below LOG_LEVEL is never written, and the SQL, outgoing-HTTP and model loggers have levels of their own (DB_LOG_LEVEL and friends default to warn, so only the slow and the failed reach a tap until they are turned up).

func WithLogger

func WithLogger(l ILogger) Option

WithLogger overrides the base logger.

func WithMQ

func WithMQ(mq IMQ) Option

WithMQ registers the message-queue publisher.

func WithMailer

func WithMailer(m IMailer) Option

WithMailer registers the mailer. Pass NewMemoryMailer() in a test to assert on what a service would have sent.

func WithMongo

func WithMongo(name string, m IMongoDB) Option

WithMongo registers a Mongo connection under name ("default" for the primary).

func WithPusher

func WithPusher(p IPusher) Option

WithPusher registers the push-notification sender. Pass NewMemoryPusher() in a test to assert on what a service would have pushed.

func WithRequester

func WithRequester(r IRequester) Option

WithRequester overrides the shared HTTP client.

func WithSQL

func WithSQL(name string, db *gorm.DB) Option

WithSQL registers a GORM connection under name ("default" for the primary).

func WithSentry

func WithSentry(s ISentry) Option

WithSentry overrides the error tracker. Without it NewApp builds one from the configuration — a no-op tracker when no DSN is set — so error reporting is wired the same way in every environment.

func WithStorage

func WithStorage(s IStorage) Option

WithStorage registers object storage.

type Page

type Page[T any] struct {
	Items   []T      `json:"items"`
	Total   int64    `json:"total"`
	Count   int64    `json:"count"`
	Page    int64    `json:"page"`
	Limit   int64    `json:"limit"`
	Q       string   `json:"q,omitempty"`
	OrderBy []string `json:"order_by,omitempty"`
}

Page is a generic paginated result.

func MapPage

func MapPage[T, R any](p *Page[T], f func(T) R) *Page[R]

MapPage turns a Page[T] into a Page[R], keeping the pagination metadata and running f over each item — for handing a response type back to the client instead of the model that was queried. (v1 called this MapPaginatedItems.)

page, err := repository.New[User](ctx).Pagination(opts)
return c.JSON(http.StatusOK, core.MapPage(page, toUserResponse))

func NewPage

func NewPage[T any](items []T, total int64, opts *PageOptions) *Page[T]

NewPage assembles a Page around items the caller produced itself — a raw SQL query, a search index, a list stitched together from several sources. Paginate and MongoPaginate already return one; this is for the cases they do not cover.

The metadata comes from opts, so it reports the same clamped limit and page the query should have used. total is the size of the whole result, not of items.

func Paginate

func Paginate[T any](db *gorm.DB, dest *[]T, opts *PageOptions) (*Page[T], error)

Paginate runs a counted, ordered, limited query into dest and returns a Page.

type PageOptions

type PageOptions struct {
	Q       string
	Limit   int64
	Page    int64
	OrderBy []string
}

PageOptions carries list query parameters parsed from the request.

type ParamField

type ParamField struct {
	Name string    `json:"name"`
	Kind ParamKind `json:"kind"`
	// Label is the display name, when the field name is not what a human should
	// read (translations, wording).
	Label       string   `json:"label,omitempty"`
	Required    bool     `json:"required,omitempty"`
	Enum        []string `json:"enum,omitempty"`
	Default     string   `json:"default,omitempty"`
	Description string   `json:"description,omitempty"`
	Example     string   `json:"example,omitempty"`

	// Options is Enum with a label per value, for a select whose text differs
	// from the value sent. Enum stays populated alongside it.
	Options []ParamOption `json:"options,omitempty"`

	// Min/Max bound a number, a string's length, or an array's size.
	Min *float64 `json:"min,omitempty"`
	Max *float64 `json:"max,omitempty"`
	// Pattern is a regular expression the value should match.
	Pattern string `json:"pattern,omitempty"`
	// Multiline asks for a text area rather than a single-line input.
	Multiline bool `json:"multiline,omitempty"`

	Items  *ParamField  `json:"items,omitempty"`  // element type of an array
	Fields []ParamField `json:"fields,omitempty"` // members of an object

	// Meta carries anything this framework does not model — a widget name, a
	// form group, an ordering hint, whatever your UI needs. It is passed through
	// untouched.
	Meta map[string]any `json:"meta,omitempty"`
}

ParamField describes one parameter of a job: what it is called, what shape it takes, whether it is required, and anything else a form needs. It is what the admin API publishes.

Build these with the Params helper rather than by hand:

core.JobDef{
    Name: "sales-report",
    Params: core.Params(
        core.DateParam("date").Required().Desc("Day to report on").Example("2026-07-01"),
        core.EnumParam("status", "draft", "sent", "paid").Default("sent"),
        core.IntParam("limit").Desc("Maximum rows"),
        core.BoolParam("force"),
        core.ArrayParam("emails", core.StringParam("")),
    ),
}

func ParamSchemaOf

func ParamSchemaOf[T any]() []ParamField

ParamSchemaOf derives a basic schema from T — the field names (from their json tags) and their kinds. It is the fallback for jobs that do not declare their parameters: it cannot know which fields are required, which are enums, or what any of them mean, so declare JobDef.Params when that matters.

It returns nil when T has no fields to describe (no parameters, or a free-form map).

func Params

func Params(specs ...*ParamSpec) []ParamField

Params turns declared specs into the schema stored on JobDef.

type ParamKind

type ParamKind string

ParamKind is the shape of a job parameter, in terms an admin UI can render a form from.

const (
	ParamString   ParamKind = "string"
	ParamInt      ParamKind = "int"
	ParamNumber   ParamKind = "number"
	ParamBool     ParamKind = "bool"
	ParamDate     ParamKind = "date"     // YYYY-MM-DD
	ParamTime     ParamKind = "time"     // HH:mm:ss
	ParamDateTime ParamKind = "datetime" // RFC3339
	ParamEnum     ParamKind = "enum"
	ParamArray    ParamKind = "array"
	ParamObject   ParamKind = "object"
	ParamAny      ParamKind = "any"
)

type ParamOption

type ParamOption struct {
	Value string `json:"value"`
	Label string `json:"label,omitempty"`
}

ParamOption is one choice of an enum, with the text to show for it.

func Opt

func Opt(value string, label ...string) ParamOption

Opt builds an enum option. Pass no label to reuse the value.

type ParamSpec

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

ParamSpec builds a ParamField. Every method returns the spec, so rules read as one chain.

func AnyParam

func AnyParam(name string) *ParamSpec

AnyParam declares a parameter with no fixed shape (a free-form value).

func ArrayParam

func ArrayParam(name string, item *ParamSpec) *ParamSpec

ArrayParam declares a list. item describes one element; its name is ignored.

func BoolParam

func BoolParam(name string) *ParamSpec

BoolParam declares a true/false parameter.

func CustomParam

func CustomParam(name string, kind ParamKind) *ParamSpec

CustomParam declares a parameter of a kind this package does not define — a widget of your own ("duration", "currency", "user-picker"). Everything else works the same; consumers that do not know the kind fall back to a text input.

core.CustomParam("payout", "currency").
    Meta("currency", "THB").
    Desc("Amount to pay out")

func DateParam

func DateParam(name string) *ParamSpec

DateParam declares a calendar date (YYYY-MM-DD).

func DateTimeParam

func DateTimeParam(name string) *ParamSpec

DateTimeParam declares an instant (RFC3339).

func EnumParam

func EnumParam(name string, values ...string) *ParamSpec

EnumParam declares a parameter limited to a fixed set of values.

func IntParam

func IntParam(name string) *ParamSpec

IntParam declares a whole-number parameter.

func NumberParam

func NumberParam(name string) *ParamSpec

NumberParam declares a decimal parameter.

func ObjectParam

func ObjectParam(name string, fields ...*ParamSpec) *ParamSpec

ObjectParam declares a nested object with its own fields.

func StringParam

func StringParam(name string) *ParamSpec

StringParam declares a free-text parameter.

func TimeParam

func TimeParam(name string) *ParamSpec

TimeParam declares a wall-clock time (HH:mm:ss).

func (*ParamSpec) Between

func (s *ParamSpec) Between(min, max float64) *ParamSpec

Between is Min and Max together.

func (*ParamSpec) Build

func (s *ParamSpec) Build() ParamField

Build returns the described field.

func (*ParamSpec) Default

func (s *ParamSpec) Default(value string) *ParamSpec

Default records the value used when the caller supplies none.

func (*ParamSpec) Desc

func (s *ParamSpec) Desc(description string) *ParamSpec

Desc sets the human explanation shown next to the field.

func (*ParamSpec) Enum

func (s *ParamSpec) Enum(values ...string) *ParamSpec

Enum restricts the parameter to a fixed set of values.

func (*ParamSpec) Example

func (s *ParamSpec) Example(value string) *ParamSpec

Example records a sample value, for placeholder text and documentation.

func (*ParamSpec) Kind

func (s *ParamSpec) Kind(kind ParamKind) *ParamSpec

Kind overrides the shape, for the rare case the constructors do not cover.

func (*ParamSpec) Label

func (s *ParamSpec) Label(label string) *ParamSpec

Label sets the display name shown instead of the field name.

func (*ParamSpec) Max

func (s *ParamSpec) Max(v float64) *ParamSpec

Max bounds a number, a string's length, or an array's size.

func (*ParamSpec) Meta

func (s *ParamSpec) Meta(key string, value any) *ParamSpec

Meta attaches an arbitrary attribute, for anything this package does not model — a widget name, a form group, an ordering hint. Values are passed through to the API untouched.

core.StringParam("region").Meta("widget", "map").Meta("group", "targeting")

func (*ParamSpec) Min

func (s *ParamSpec) Min(v float64) *ParamSpec

Min bounds a number, a string's length, or an array's size.

func (*ParamSpec) Multiline

func (s *ParamSpec) Multiline() *ParamSpec

Multiline asks for a text area rather than a single-line input.

func (*ParamSpec) Options

func (s *ParamSpec) Options(options ...ParamOption) *ParamSpec

Options restricts the parameter to a fixed set of values, each with the text to show for it — the labelled form of Enum.

core.StringParam("status").Options(
    core.Opt("draft", "ฉบับร่าง"),
    core.Opt("sent", "ส่งแล้ว"),
)

func (*ParamSpec) Pattern

func (s *ParamSpec) Pattern(expr string) *ParamSpec

Pattern sets a regular expression the value should match.

func (*ParamSpec) Required

func (s *ParamSpec) Required() *ParamSpec

Required marks the parameter as one the caller must supply.

This is what a form shows a human; it does not validate anything. Enforcement stays in the payload's Valid method — deliberately, because a job that is also scheduled has to tolerate empty parameters even while the form marks them required.

func (*ParamSpec) With

func (s *ParamSpec) With(fn func(*ParamField)) *ParamSpec

With applies an arbitrary change to the field being built — the escape hatch for a house style, so a team can wrap its own conventions in one helper:

func tenantID() *core.ParamSpec {
    return core.StringParam("tenant_id").Required().
        With(func(f *core.ParamField) { f.Pattern = "^t_[a-z0-9]+$" })
}

type PubSubHandler

type PubSubHandler func(ctx IContext, msg *PubSubMessage) error

PubSubHandler handles one delivery. The context is a full IContext — logger, database, cache, Sentry — built for that message and cancelled when the handler's timeout runs out.

Returning an error logs and reports it. There is no redelivery: pub/sub has no acknowledgement, so a handler that must not lose work should write what it received somewhere durable (a job, a row) before doing anything slow.

type PubSubMessage

type PubSubMessage struct {
	// Channel is the channel the message arrived on, without the prefix.
	Channel string
	// Pattern is the glob that matched, for a pattern subscription. Empty for
	// an exact one.
	Pattern string
	Payload []byte
}

PubSubMessage is one delivery. Payload is the raw bytes as published; Bind decodes them.

func (*PubSubMessage) Bind

func (m *PubSubMessage) Bind(dest any) IError

Bind decodes the payload into dest, following the same rules as ICache.Get: *string, *[]byte and *json.RawMessage take the raw bytes, anything else is JSON-decoded.

func (*PubSubMessage) String

func (m *PubSubMessage) String() string

String renders the payload as text, for logs.

type PublishOptions

type PublishOptions struct {
	// ContentType defaults to application/json (text/plain for a []byte body).
	ContentType string
	// Headers travel with the message. A headers exchange routes on them, and a
	// consumer reads them for tracing and versioning.
	Headers map[string]any
	// MessageID, CorrelationID and ReplyTo are the request/reply and
	// deduplication fields. Set MessageID to something stable when the consumer
	// deduplicates.
	MessageID     string
	CorrelationID string
	ReplyTo       string
	// Type names the event ("order.created"), for a consumer that reads several
	// kinds off one queue.
	Type string
	// AppID and UserID identify the sender. UserID is verified by the broker
	// against the connection's login, so set it only when they match.
	AppID  string
	UserID string
	// Priority is 0-9, and only means anything on a queue declared with
	// x-max-priority.
	Priority uint8
	// Expiration discards the message if it has not been delivered in time.
	// This is per-message TTL; the queue may have its own, and the shorter wins.
	Expiration time.Duration
	// Transient stores the message in memory only. It is lost when the broker
	// restarts — for a stream of updates where the next one supersedes this one.
	Transient bool
	// Mandatory returns the message instead of discarding it when no queue is
	// bound to match it, turning a silent misroute into an error the publisher
	// sees. It costs a round trip.
	Mandatory bool
	// Timestamp defaults to now.
	Timestamp time.Time
}

PublishOptions are the per-message properties AMQP carries beside the body. The zero value is what Publish sends: persistent, JSON, timestamped.

type PushMessage

type PushMessage struct {
	Title string
	Body  string
	// Image is a URL shown with the notification.
	Image string
	// Data is the custom payload. FCM carries strings only.
	Data map[string]string

	// Android, APNS and Web tune one platform each: channel and priority on
	// Android, sound and badge on iOS, actions and icon on the web. A config set
	// here is used as it is, and the shorthand fields below are ignored for that
	// platform.
	Android    *messaging.AndroidConfig
	APNS       *messaging.APNSConfig
	Web        *messaging.WebpushConfig
	FCMOptions *messaging.FCMOptions

	// Sound, Badge, ChannelID and Priority are the settings wanted often enough
	// not to be worth building a platform config for.
	Sound     string
	Badge     *int
	ChannelID string
	Priority  PushPriority

	// TTL is how long FCM keeps trying. Zero is the provider's default (four
	// weeks); a short one suits a message that is worthless when it is late.
	TTL time.Duration

	// CollapseKey replaces any undelivered message carrying the same key, so a
	// device coming back online gets the latest rather than the backlog.
	CollapseKey string
}

PushMessage is a notification to deliver.

Notification (Title/Body) is what the device shows; Data is what the app receives. A message with only Data is a silent one — delivered to the app without the system drawing anything — which is how a background sync is triggered.

type PushPriority

type PushPriority uint8

PushPriority is how urgently the device should be woken.

const (
	// PushPriorityNormal lets the device batch the delivery to save battery.
	PushPriorityNormal PushPriority = iota
	// PushPriorityHigh wakes the device immediately. Reserve it for messages a
	// person is waiting for: providers throttle a sender that marks everything
	// high.
	PushPriorityHigh
)

type PushResult

type PushResult struct {
	Token     string
	Success   bool
	MessageID string
	// Error is the per-token failure. It wraps ErrPushUnregistered when the
	// token is dead and should be deleted.
	Error error
}

PushResult is one token's outcome inside a batch.

type PusherOption

type PusherOption func(*pusherConfig)

PusherOption tunes a pusher at construction.

func WithPushClientOptions

func WithPushClientOptions(opts ...option.ClientOption) PusherOption

WithPushClientOptions passes Google API client options through — a custom HTTP client, an alternative credential source.

func WithPushProjectID

func WithPushProjectID(id string) PusherOption

WithPushProjectID names the Firebase project explicitly, for credentials that do not carry one.

func WithPushTimeout

func WithPushTimeout(d time.Duration) PusherOption

WithPushTimeout bounds one send (default DefaultPushTimeout).

type QueueConfig

type QueueConfig struct {
	Name string
	// Transient makes the queue not survive a broker restart.
	Transient bool
	// AutoDelete removes the queue when its last consumer disconnects.
	AutoDelete bool
	// Exclusive limits the queue to this connection and deletes it on close.
	Exclusive bool
	// TTL discards a message that has waited this long.
	TTL time.Duration
	// MaxLength and MaxBytes bound the queue; past them the oldest messages are
	// dropped (or dead-lettered).
	MaxLength int64
	MaxBytes  int64
	// MaxPriority turns this into a priority queue (1-255).
	MaxPriority uint8
	// DeadLetterExchange is where a rejected, expired or overflowing message
	// goes. Declare one for any queue whose failures matter: without it a
	// message a consumer rejects is simply gone.
	DeadLetterExchange string
	// DeadLetterRoutingKey overrides the routing key used when dead-lettering.
	DeadLetterRoutingKey string
	// Quorum makes this a quorum queue — replicated across the cluster, at the
	// cost of throughput. For work that must survive losing a node.
	Quorum bool
	// Args are extra arguments, merged after the fields above.
	Args map[string]any
}

QueueConfig declares a queue.

type QueueInfo

type QueueInfo struct {
	Name      string
	Messages  int
	Consumers int
}

QueueInfo is what the broker reports about a declared queue.

type ReplayOptions

type ReplayOptions struct {
	By string
	// Params overrides the original parameters when non-nil.
	Params any
	// CaptureLogs overrides the log policy for the replay.
	CaptureLogs *LogPolicy
}

Replay re-runs a finished run as a *new* run, keeping the original intact — history must never be overwritten.

type RunError

type RunError struct {
	Code    string `json:"code,omitempty"`
	Status  int    `json:"status,omitempty"`
	Message string `json:"message"`
	// Fields carries per-field violations when the failure was a validation
	// error — the same shape the HTTP layer returns, so bad parameters are as
	// readable on a run as they are on a request.
	Fields json.RawMessage `json:"fields,omitempty"`
	Stack  string          `json:"stack,omitempty"`
	// Tail holds the last lines logged before the failure. It is kept even when
	// the log policy is LogOff, so a failed run is always debuggable.
	Tail []string `json:"tail,omitempty"`
}

RunError is the failure recorded on a run.

type RunStatus

type RunStatus string

RunStatus is the lifecycle state of a single run.

const (
	RunQueued    RunStatus = "queued"
	RunRunning   RunStatus = "running"
	RunSucceeded RunStatus = "succeeded"
	RunFailed    RunStatus = "failed"
	RunCanceled  RunStatus = "canceled"
	RunSkipped   RunStatus = "skipped"
)

func (RunStatus) IsTerminal

func (s RunStatus) IsTerminal() bool

IsTerminal reports whether no further transition is possible from s.

type Runner

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

Runner starts the parts of a service and, more importantly, stops them in the right order.

Shutting a service down is not "close everything": it is a sequence, and getting it wrong is what turns a deploy into a burst of 500s and half-finished jobs. The order is always

  1. stop taking new work — refuse new connections, stop the cron ticking, stop pulling from the queue
  2. let the work in flight finish, up to a deadline
  3. only then close the pools it was using

StartHTTPServer does this for a process that only serves HTTP. Runner does it for one that also runs jobs, a scheduler and pub/sub subscribers — where the sequence is easy to write by hand and easier to get wrong.

r := core.NewRunner(app,
    core.RunHTTP(e),
    core.RunScheduler(sc),
    core.RunJobs(sc.Runner()),
)
if err := r.Run(); err != nil {
    log.Fatal(err)
}

func NewRunner

func NewRunner(app *App, opts ...RunnerOption) *Runner

NewRunner builds a Runner. Nothing starts until Run.

func (*Runner) Run

func (r *Runner) Run() error

Run starts everything and blocks until a shutdown signal arrives, then stops it all in order. It returns the first error of the whole lifecycle.

func (*Runner) RunContext

func (r *Runner) RunContext(ctx context.Context) error

RunContext is Run bounded by a context of the caller's own — for a test, or a process whose shutdown is triggered by something other than a signal.

func (*Runner) Stop

func (r *Runner) Stop() error

Stop triggers the shutdown from outside Run — for a test, or a service that decides to stop itself.

type RunnerOption

type RunnerOption func(*Runner)

RunnerOption configures a Runner.

func AfterStop

func AfterStop(fn func()) RunnerOption

AfterStop registers a hook to run once everything is closed — the last thing before the process exits.

func BeforeStop

func BeforeStop(fn func(context.Context) error) RunnerOption

BeforeStop registers a hook to run at the start of the shutdown, before anything is drained — deregistering from a service registry, say, so traffic stops arriving before the drain begins rather than during it.

func RunHTTP

func RunHTTP(e *Server) RunnerOption

RunHTTP serves HTTP. The server is drained before anything is closed.

func RunJobs

func RunJobs(j *JobRunner) RunnerOption

RunJobs works the job queue. Give the Runner the same JobRunner the scheduler feeds — passing both is how in-flight runs get to finish.

func RunMQ

func RunMQ(c ...IMQConsumer) RunnerOption

RunMQ consumes queues. Consumers stop first in the shutdown, with the scheduler: both are sources of new work, and a message accepted during the drain is a handler racing the pools it is about to lose.

It exists because a consumer cannot be passed to RunService — IMQConsumer returns IError where RunnerService returns error, and a nil IError handed back as an error is not nil.

func RunModules

func RunModules(set *ModuleSet) RunnerOption

RunModules mounts a ModuleSet onto whatever this Runner was given: jobs and cron when it has a scheduler, routes when it has a server, consumers when it has one. An extension point with no target is skipped and named in the boot line, so "this role does not arm cron" is a thing the log says rather than a thing somebody works out from a job that never ran.

core.NewRunner(app,
    core.RunHTTP(e),
    core.RunScheduler(sc),
    core.RunJobs(sc.Runner()),
    core.RunModules(mods),
)

func RunScheduler

func RunScheduler(sc *Scheduler) RunnerOption

RunScheduler ticks cron jobs. It is stopped first, so no new run is queued during the drain.

func RunService

func RunService(s ...RunnerService) RunnerOption

RunService adds anything else with a Start and a Stop.

func WithCloseTimeout

func WithCloseTimeout(d time.Duration) RunnerOption

WithCloseTimeout bounds closing the pools, after the drain (default DefaultGracefulTimeout).

func WithDrainTimeout

func WithDrainTimeout(d time.Duration) RunnerOption

WithDrainTimeout bounds how long in-flight requests and job runs have to finish once the shutdown starts (default DefaultGracefulTimeout).

Set it below the orchestrator's own grace period — Kubernetes' terminationGracePeriodSeconds — or the process is killed mid-drain and the ordering this type exists for never happens.

type RunnerService

type RunnerService interface {
	Start() error
	Stop(ctx context.Context) error
}

RunnerService is anything else with a start and a stop — a gRPC server, a third-party consumer, a metrics exporter. Start must not block.

type Schedule

type Schedule interface {
	String() string
	// contains filtered or unexported methods
}

Schedule describes when a job runs automatically. Build one with Cron, CronWithSeconds or Every; a job with no schedule is manual-only.

func Cron

func Cron(expr string) Schedule

Cron schedules on a standard 5-field cron expression, read in the process's own time zone — which in a container with no TZ set is UTC, not where the people reading the schedule live. Use CronIn when the hour has to mean a particular zone.

func CronIn

func CronIn(loc *time.Location, expr string) Schedule

CronIn is Cron read in loc, whatever the process's own zone is:

core.CronIn(bangkok, "0 22 * * *") // 22:00 in Bangkok, always

func CronWithSeconds

func CronWithSeconds(expr string) Schedule

CronWithSeconds schedules on a 6-field expression whose first field is seconds.

func CronWithSecondsIn

func CronWithSecondsIn(loc *time.Location, expr string) Schedule

CronWithSecondsIn is CronWithSeconds read in loc.

func Every

func Every(d time.Duration) Schedule

Every schedules a job to run at a fixed interval.

type Scheduler

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

Scheduler turns schedules into queued runs. It deliberately does *not* execute anything: a tick enqueues a run exactly like a manual trigger does, so scheduled and manual work share one path — and therefore one implementation of status, logging, retries, concurrency and cancellation.

func (*Scheduler) Add

func (sc *Scheduler) Add(def JobDef, fn JobFunc) IError

Add registers a job and, when it has a Schedule, arms it.

func (*Scheduler) AddByCron

func (sc *Scheduler) AddByCron(name, cronExpr string, fn JobFunc) IError

AddByCron schedules fn on a cron expression (v1-compatible shorthand).

func (*Scheduler) AddByDuration

func (sc *Scheduler) AddByDuration(name string, d time.Duration, fn JobFunc) IError

AddByDuration schedules fn to run every d (v1-compatible shorthand).

func (*Scheduler) Runner

func (sc *Scheduler) Runner() *JobRunner

Runner returns the runner the scheduler feeds.

func (*Scheduler) Start

func (sc *Scheduler) Start() IError

Start arms every scheduled job in the registry and begins ticking. It is non-blocking. When the scheduler owns its runner, that is started too.

func (*Scheduler) Stop

func (sc *Scheduler) Stop() IError

Stop halts scheduling. In-flight runs are the runner's business — stop it separately (or let Stop do it when the scheduler owns the runner).

type SchedulerOption

type SchedulerOption interface {
	// contains filtered or unexported methods
}

SchedulerOption configures a Scheduler at construction.

*JobRunner is one, which is what keeps the original form of the call — NewScheduler(app, runner) — meaning exactly what it always did.

func WithSchedulerLocation

func WithSchedulerLocation(loc *time.Location) SchedulerOption

WithSchedulerLocation sets the time zone every cron expression is read in, for the whole scheduler:

sc, _ := core.NewScheduler(app, runner, core.WithSchedulerLocation(bangkok))
sc.AddByCron("nightly", "0 22 * * *", Report) // 22:00 in Bangkok

Without it a schedule is read in the process's own zone, which in a container with no TZ set is UTC — the whole table shifts at once and nothing errors. A schedule built with CronIn carries its own zone and overrides this.

type SentPush

type SentPush struct {
	Tokens    []string
	Topic     string
	Condition string
	Message   PushMessage
	// DryRun is set for a Validate call.
	DryRun bool
}

SentPush is one delivery a memory pusher recorded. Exactly one of Tokens, Topic and Condition is set.

func SentPushes

func SentPushes(p IPusher) []SentPush

SentPushes returns what a memory pusher recorded, in order. Nil for any other pusher.

type SentryGormOptions

type SentryGormOptions struct {
	// SlowQuery is the threshold above which a query is recorded at warning
	// level. 0 = 200ms.
	SlowQuery time.Duration
	// AllQueries records every query, not only the slow and the failing ones.
	// Off by default: a busy request would spend its whole breadcrumb budget on
	// SELECTs and push out the crumbs that explain the failure.
	AllQueries bool
	// ExcludeSQL leaves the statement out of the breadcrumb, keeping only the
	// table, row count and timing. Bind variables are never interpolated, so the
	// statement is safe by default — this is for teams whose SQL is itself
	// sensitive.
	ExcludeSQL bool
}

SentryGormOptions tunes the database instrumentation.

type SentryOptions

type SentryOptions struct {
	DSN         string
	Environment string
	Release     string
	ServerName  string

	Debug              *bool
	SampleRate         *float64
	TracesSampleRate   *float64
	TracesSampler      sentry.TracesSampler
	AttachStacktrace   *bool
	SendDefaultPII     *bool
	IgnoreErrors       []string
	IgnoreTransactions []string
	MaxBreadcrumbs     int

	// MinStatus is the lowest IError status that is reported automatically.
	// Default 500 — client mistakes are not incidents.
	MinStatus int
	// CaptureRetries reports every failed attempt of a job instead of only the
	// final one. Default false.
	CaptureRetries *bool
	// BreadcrumbLevel is the lowest log level turned into a breadcrumb
	// ("debug"|"info"|"warn"|"error"|"off"). Default "info".
	BreadcrumbLevel string
	// EnableTracing turns on performance transactions for requests and job runs.
	// Default false (tracing has its own quota).
	EnableTracing *bool
	// EnableCrons sends check-ins for scheduled jobs, so Sentry alerts on a run
	// that never happened. Default false — it creates monitors in your org.
	EnableCrons *bool
	// EnableLogs streams every log line to Sentry Logs, where it is searchable on
	// its own and correlated with the trace and the issue it belongs to. Default
	// false — logs have their own quota.
	EnableLogs *bool
	// EnableMetrics lets ctx.Meter() record counters, gauges and distributions.
	// Default false — metrics have their own quota.
	EnableMetrics *bool
	// LogLevel is the lowest level streamed to Sentry Logs
	// ("debug"|"info"|"warn"|"error"). Default: everything the logger emits, so
	// LOG_LEVEL alone decides — raise this only to send Sentry less than you
	// print.
	LogLevel string
	// CaptureRequestBody attaches the (scrubbed) request body of a failed
	// request. Default true.
	CaptureRequestBody *bool
	// MaxBodyBytes caps how much of a body is recorded. Default 16 KiB.
	MaxBodyBytes int
	// SendEnv attaches the (scrubbed) configuration to every event. Default true.
	SendEnv *bool

	// ScrubKeys extends the list of key fragments whose values are masked.
	ScrubKeys []string
	// ScrubValues masks these exact strings wherever they appear.
	ScrubValues []string

	// Tags are attached to every event of the process.
	Tags map[string]string
	// BeforeSend is the last hook before an event leaves; return nil to drop it.
	// It runs after the framework's scrubbing.
	BeforeSend func(event *sentry.Event, hint *sentry.EventHint) *sentry.Event
	// BeforeSendLog is the last hook before a log line leaves; return nil to drop
	// it. It runs after the framework's scrubbing.
	BeforeSendLog func(log *sentry.Log) *sentry.Log
	// BeforeSendMetric is the last hook before a measurement leaves; return nil
	// to drop it. It runs after the framework's scrubbing.
	BeforeSendMetric func(metric *sentry.Metric) *sentry.Metric
	// Transport replaces the HTTP transport — this is what tests swap out.
	Transport sentry.Transport
	// FlushTimeout bounds Close/Flush. Default 5s.
	FlushTimeout time.Duration
}

SentryOptions overrides what NewSentry reads from the environment. A zero field keeps the configured (or default) value; the *bool / *float64 fields exist so "false" and "0" can be told apart from "not set".

type SentryRecorder

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

SentryRecorder captures the events a tracker would have sent, instead of sending them. It is the job store's in-memory twin, for error reporting: it lets a service assert that a failure is actually reported — and with what — without a network, a DSN or a Sentry account.

tracker, rec := core.NewRecordingSentry(env)
app, _ := core.NewApp(env, core.WithSentry(tracker))
...
if got := rec.Codes(); !slices.Contains(got, "DATABASE_ERROR") { t.Fatal(got) }

func NewSentryRecorder

func NewSentryRecorder() *SentryRecorder

NewSentryRecorder builds an empty recorder.

func (*SentryRecorder) Close

func (r *SentryRecorder) Close()

func (*SentryRecorder) Codes

func (r *SentryRecorder) Codes() []string

Codes returns the error code of every recorded error event, in order.

func (*SentryRecorder) Configure

func (r *SentryRecorder) Configure(sentry.ClientOptions)

func (*SentryRecorder) Errors

func (r *SentryRecorder) Errors() []*sentry.Event

Errors returns the recorded error events, leaving out transactions and cron check-ins.

func (*SentryRecorder) Events

func (r *SentryRecorder) Events() []*sentry.Event

Events returns every recorded event, oldest first.

func (*SentryRecorder) Flush

func (r *SentryRecorder) Flush(time.Duration) bool

func (*SentryRecorder) FlushWithContext

func (r *SentryRecorder) FlushWithContext(context.Context) bool

func (*SentryRecorder) HasBreadcrumb

func (r *SentryRecorder) HasBreadcrumb(substr string) bool

HasBreadcrumb reports whether any recorded event carries a breadcrumb whose message contains substr.

func (*SentryRecorder) HasLog

func (r *SentryRecorder) HasLog(substr string) bool

HasLog reports whether any streamed log line's body contains substr.

func (*SentryRecorder) Last

func (r *SentryRecorder) Last() *sentry.Event

Last returns the most recent error event, or nil.

func (*SentryRecorder) Len

func (r *SentryRecorder) Len() int

Len is how many error events were recorded.

func (*SentryRecorder) Logs

func (r *SentryRecorder) Logs() []sentry.Log

Logs returns every line streamed to Sentry Logs, oldest first. Log lines are batched by the SDK, so call ISentry.Flush before asserting on them:

app.Sentry().Flush(time.Second)
require.True(t, rec.HasLog("charge failed"))

func (*SentryRecorder) Metric

func (r *SentryRecorder) Metric(name string) *sentry.Metric

Metric returns the last measurement recorded under name, or nil.

func (*SentryRecorder) Metrics

func (r *SentryRecorder) Metrics() []sentry.Metric

Metrics returns every measurement the tracker recorded, oldest first. Like logs they are batched, so call ISentry.Flush before asserting on them.

func (*SentryRecorder) Reset

func (r *SentryRecorder) Reset()

Reset drops everything recorded so far.

func (*SentryRecorder) SendEvent

func (r *SentryRecorder) SendEvent(event *sentry.Event)

type Server

type Server struct {
	*echo.Echo
	// contains filtered or unexported fields
}

Server wraps Echo and remembers the App, so route registration takes the handler directly — no need to thread app through every call. It embeds *echo.Echo, so every Echo method (Use, Static, Pre, Logger, ...) is available.

func NewHTTPServer

func NewHTTPServer(app *App, opts *HTTPOptions) *Server

NewHTTPServer builds a Server with the standard middleware stack (request-id, logger, recover, CORS) and an error handler that renders IError.

func (*Server) App

func (s *Server) App() *App

App returns the App the server was built on.

The point of Server is that a route does not have to be handed the App; this is for the cases that still need it, chiefly middleware built at startup — authentication that resolves a token against the database, say. Without it a module's registration function has to take the App as a second parameter purely to pass it on, which is the threading Server exists to remove.

func (*Server) DELETE

func (s *Server) DELETE(path string, h HandlerFunc, m ...echo.MiddlewareFunc) echo.RouteInfo

func (*Server) GET

func (s *Server) GET(path string, h HandlerFunc, m ...echo.MiddlewareFunc) echo.RouteInfo

func (*Server) Group

func (s *Server) Group(prefix string, m ...echo.MiddlewareFunc) *Group

Group creates a route group that also carries the App.

func (*Server) HandlerNames

func (s *Server) HandlerNames() map[string]string

HandlerNames maps "METHOD /path" to the name of the function serving it, for every route registered through the framework's own helpers — what the devtools route list shows, and what an operator asks when a path answers something unexpected. Routes registered straight on the embedded Echo are absent: their handler was never an mine-core HandlerFunc.

func (*Server) PATCH

func (s *Server) PATCH(path string, h HandlerFunc, m ...echo.MiddlewareFunc) echo.RouteInfo

func (*Server) POST

func (s *Server) POST(path string, h HandlerFunc, m ...echo.MiddlewareFunc) echo.RouteInfo

func (*Server) PUT

func (s *Server) PUT(path string, h HandlerFunc, m ...echo.MiddlewareFunc) echo.RouteInfo

func (*Server) Serve

func (s *Server) Serve(ctx context.Context, cfg echo.StartConfig) error

Serve runs the server with a StartConfig of your own — a listener you already hold, TLS, a different graceful timeout — and blocks until ctx is cancelled or Shutdown is called. StartHTTPServer is this with the framework's defaults.

func (*Server) Shutdown

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

Shutdown stops a running server and waits for in-flight requests to finish, or until ctx expires. It is a no-op when the server was never started, so the same shutdown sequence is safe in a service that only runs jobs.

echo v5 removed Echo.Shutdown; this is the framework's replacement and keeps the call that services already make working.

type Stoppable

type Stoppable interface {
	Stop(ctx context.Context) IError
}

Stoppable is a background reader the App must stop before it closes the connections that reader is using — a pub/sub subscriber, a queue consumer.

type StorageListOptions

type StorageListOptions struct {
	// Limit caps how many objects are returned. 0 means every one, which for a
	// large bucket is many round trips and a large slice — pass a limit unless
	// the prefix is known to be small.
	Limit int
}

StorageListOptions bounds a listing.

type StorageObject

type StorageObject struct {
	// Key is the object's key without the storage prefix — the same name it was
	// written under.
	Key          string
	Size         int64
	ContentType  string
	ETag         string
	LastModified time.Time
	Metadata     map[string]string
}

StorageObject is what the store knows about one object.

type StorageOption

type StorageOption func(*storage)

StorageOption tunes a store at construction.

func WithStoragePrefix

func WithStoragePrefix(prefix string) StorageOption

WithStoragePrefix namespaces every key. It overrides S3_PREFIX.

type StoragePresignOptions

type StoragePresignOptions struct {
	// Attachment makes the link download under this filename.
	Attachment string
	// ContentType overrides the stored type for this link only.
	ContentType string
}

StoragePresignOptions tunes a presigned GET: what the browser is told the object is, rather than what it is stored as.

type StoragePutOptions

type StoragePutOptions struct {
	// ContentType is what browsers will trust. Guessed from the extension when
	// empty, falling back to application/octet-stream.
	ContentType string
	// Attachment sets Content-Disposition so a download is offered under this
	// filename instead of being rendered inline.
	Attachment string
	// ContentDisposition is set verbatim, overriding Attachment.
	ContentDisposition string
	ContentEncoding    string
	CacheControl       string
	// Metadata becomes x-amz-meta-* headers, returned again by Stat.
	Metadata map[string]string
	// Public marks the object world-readable. It only works on buckets that
	// still allow object ACLs — most modern S3 buckets do not, and serve public
	// objects through a bucket policy or a CDN instead.
	Public bool
}

StoragePutOptions describes how an object is stored. Every field is optional; an empty ContentType is guessed from the key's extension.

Methods take it variadically so the common call stays short:

store.Put("avatars/u1.png", r)
store.Put("reports/1.pdf", r, core.StoragePutOptions{Attachment: "report.pdf"})

type SubscriberOption

type SubscriberOption func(*subscriberOptions)

SubscriberOption tunes a subscriber.

func WithSubscriberCache

func WithSubscriberCache(name string) SubscriberOption

WithSubscriberCache picks which registered cache to subscribe on. Defaults to "default".

func WithSubscriberConcurrency

func WithSubscriberConcurrency(n int) SubscriberOption

WithSubscriberConcurrency allows n handlers to run at once. The default is 1, which keeps messages in the order they arrived; raising it trades that order for throughput, so raise it only when the handlers are independent.

func WithSubscriberTimeout

func WithSubscriberTimeout(d time.Duration) SubscriberOption

WithSubscriberTimeout bounds one handler. The default is 30s; a handler that overruns has its context cancelled, which is what stops a stuck message from holding the only worker forever.

type TokenVerifier

type TokenVerifier func(ctx context.Context, token string) (*ContextUser, error)

TokenVerifier turns a raw bearer token into a ContextUser, or an error when the token is invalid. ctx is the request context (for DB/cache lookups). This is the strategy that lets Auth support JWTs, opaque/hashed tokens, or both.

func ChainVerifiers

func ChainVerifiers(verifiers ...TokenVerifier) TokenVerifier

ChainVerifiers tries each verifier in order and returns the first user it resolves — handy to accept both JWTs and opaque API keys on the same routes.

func HashedTokenVerifier

func HashedTokenVerifier(lookup func(ctx context.Context, tokenHash string) (*ContextUser, error)) TokenVerifier

HashedTokenVerifier builds a verifier for opaque tokens: it SHA-256-hashes the incoming token and hands the hex digest to lookup, which finds the user (e.g. by querying a table that stores token hashes). Storing only the hash means a leaked database never exposes usable tokens.

auth := core.NewAuth(core.HashedTokenVerifier(func(ctx context.Context, hash string) (*core.ContextUser, error) {
    var t AccessToken
    if err := db.WithContext(ctx).Where("token_hash = ?", hash).First(&t).Error; err != nil {
        return nil, err
    }
    return &core.ContextUser{ID: t.UserID, Segment: t.Role}, nil
}))

func JWTVerifier

func JWTVerifier(secret string, resolver ...UserResolver) TokenVerifier

JWTVerifier verifies an HS256 JWT and maps its claims via resolver (the default resolver is used when none is given).

type Trigger

type Trigger string

Trigger records what caused a run to be created.

const (
	TriggerSchedule Trigger = "schedule"
	TriggerManual   Trigger = "manual"
	TriggerRetry    Trigger = "retry"
	TriggerReplay   Trigger = "replay"
	TriggerEvent    Trigger = "event"
)

type TriggerOptions

type TriggerOptions struct {
	// By records who asked for the run (a user id, "scheduler", …).
	By string
	// IdemKey makes triggering idempotent: while a run with the same key is
	// still active, triggering again returns that run instead of creating a
	// second one. This is what stops a double-clicked button from running twice.
	IdemKey string
	// Delay postpones the run.
	Delay time.Duration
	// Trigger overrides the recorded cause (default TriggerManual).
	Trigger Trigger
	// CaptureLogs overrides the log policy for this run only.
	CaptureLogs *LogPolicy
	// MaxAttempts overrides the job's retry count for this run.
	MaxAttempts int
}

TriggerOptions tunes a single manual trigger.

type UserResolver

type UserResolver func(claims jwt.MapClaims) (*ContextUser, error)

UserResolver maps verified JWT claims to a ContextUser.

Directories

Path Synopsis
Package apidocs serves a service's own API reference from inside the service, as a page an engineer or an analyst can send requests from.
Package apidocs serves a service's own API reference from inside the service, as a page an engineer or an analyst can send requests from.
chat
slack
Package slack posts messages to Slack through core.IChat.
Package slack posts messages to Slack through core.IChat.
cmd
postmangen command
Package coretest builds the fixtures a service's tests need: an App and an IContext backed by a real database, an HTTP client that speaks the framework's error shape, and a way to run jobs.
Package coretest builds the fixtures a service's tests need: an App and an IContext backed by a real database, an HTTP client that speaks the framework's error shape, and a way to run jobs.
Package devtools mounts a small inspector on a running service: what this process was wired with, which routes exist and who serves them, what configuration it actually loaded, and what its jobs have been doing.
Package devtools mounts a small inspector on a running service: what this process was wired with, which routes exist and who serves them, what configuration it actually loaded, and what its jobs have been doing.
Package errmsgs holds reusable, framework-level *core.Error values.
Package errmsgs holds reusable, framework-level *core.Error values.
examples
ai command
Command ai is a runnable tour of the v2 AI capability: text generation, typed values, streaming, tool use, agents as jobs, embeddings and testing.
Command ai is a runnable tour of the v2 AI capability: text generation, typed values, streaming, tool use, agents as jobs, embeddings and testing.
cache command
Command cache is a runnable tour of the v2 cache: values, counters, locks, cache-aside, invalidation and testing.
Command cache is a runnable tour of the v2 cache: values, counters, locks, cache-aside, invalidation and testing.
database command
Command database is a runnable tour of the v2 SQL stack: models, the generic repository, relations, transactions, pagination, batching and named connections.
Command database is a runnable tour of the v2 SQL stack: models, the generic repository, relations, transactions, pagination, batching and named connections.
http command
Command http is a runnable tour of the v2 HTTP layer: the server and its options, binding and validating a request, the errors a client gets back, list endpoints, middleware, bearer-token auth, and file upload/download.
Command http is a runnable tour of the v2 HTTP layer: the server and its options, binding and validating a request, the errors a client gets back, list endpoints, middleware, bearer-token auth, and file upload/download.
integrations command
Command integrations is a runnable tour of the things a service talks to that are not its own database: other people's HTTP APIs, SMTP, Firebase, and the CSV files humans exchange.
Command integrations is a runnable tour of the things a service talks to that are not its own database: other people's HTTP APIs, SMTP, Firebase, and the CSV files humans exchange.
jobs command
Command jobs is a runnable tour of the v2 job runner: scheduled jobs, manual triggers with parameters, queueing, status, cancellation, concurrency limits, replay and log policies.
Command jobs is a runnable tour of the v2 job runner: scheduled jobs, manual triggers with parameters, queueing, status, cancellation, concurrency limits, replay and log policies.
mongo command
Command mongo is a runnable tour of the v2 MongoDB support: connecting, the driver layer, the typed repository, aggregation pipelines, indexes, change streams and transactions.
Command mongo is a runnable tour of the v2 MongoDB support: connecting, the driver layer, the typed repository, aggregation pipelines, indexes, change streams and transactions.
mq command
Command mq is a runnable tour of the v2 RabbitMQ integration: publishing with confirms, topology declared at boot, consuming with the right acknowledgement, retry that actually waits, and a transactional outbox.
Command mq is a runnable tour of the v2 RabbitMQ integration: publishing with confirms, topology declared at boot, consuming with the right acknowledgement, retry that actually waits, and a transactional outbox.
pubsub command
Command pubsub is a runnable tour of the v2 redis publish/subscribe support: publishing, the handler-based subscriber, raw subscriptions, and the three jobs pub/sub is genuinely the right tool for.
Command pubsub is a runnable tour of the v2 redis publish/subscribe support: publishing, the handler-based subscriber, raw subscriptions, and the three jobs pub/sub is genuinely the right tool for.
service command
Command service is a runnable skeleton of one service, from boot to shutdown.
Command service is a runnable skeleton of one service, from boot to shutdown.
storage command
Command storage is a runnable tour of core.IStorage: uploading, reading, listing, temporary links, and the arrangement that keeps a bucket and a database agreeing with each other.
Command storage is a runnable tour of core.IStorage: uploading, reading, listing, temporary links, and the arrangement that keeps a bucket and a database agreeing with each other.
Package jobstore provides durable backends for the job runner, built on the v2 repository (GORM underneath) rather than on raw *gorm.DB.
Package jobstore provides durable backends for the job runner, built on the v2 repository (GORM underneath) rather than on raw *gorm.DB.
llm
Package llm is typed generation on top of core.ILLM.
Package llm is typed generation on top of core.ILLM.
goai
Package goai adapts github.com/zendev-sh/goai to core.ILLM, so a service can talk to any of that library's providers through the framework's own interface.
Package goai adapts github.com/zendev-sh/goai to core.ILLM, so a service can talk to any of that library's providers through the framework's own interface.
llmtest
Package llmtest is the contract every core.ILLM driver must satisfy.
Package llmtest is the contract every core.ILLM driver must satisfy.
Package mongorepo provides a generic, Mongo-backed repository — the counterpart of the GORM-backed repository package, with the same shape: the context is bound once at New, query methods take no ctx, and the fluent chain is copy-on-write so a base query can be branched safely.
Package mongorepo provides a generic, Mongo-backed repository — the counterpart of the GORM-backed repository package, with the same shape: the context is bound once at New, query methods take no ctx, and the fluent chain is copy-on-write so a base query can be branched safely.
Package repository provides a generic, GORM-backed repository.
Package repository provides a generic, GORM-backed repository.
Package utils holds small, dependency-free generic helpers.
Package utils holds small, dependency-free generic helpers.
Package valid is mine-core v2's validation layer: a typed, fluent builder.
Package valid is mine-core v2's validation layer: a typed, fluent builder.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址