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
- Variables
- func BodyLimit(limit int64) echo.MiddlewareFunc
- func BoolPtr(b bool) *bool
- func CosineSimilarity(a, b []float32) float64
- func EmbeddedTexts(e IEmbedder) []string
- func Forget(c ICache, keys ...string)
- func Get[T any](ctx IContext, key string) (T, bool)
- func LockWait(c ICache, key string, ttl, wait time.Duration) (ILock, IError)
- func MongoAggregatePage[T any](m IMongoDB, collection string, pipeline []map[string]any, opts *PageOptions, ...) (*Page[T], IError)
- func MongoByID(id string) bson.M
- func MongoPaginate[T any](m IMongoDB, collection string, filter any, opts *PageOptions) (*Page[T], IError)
- func MongoSortDocument(fields []string) bson.D
- func NewApp(env IENV, opts ...Option) (*App, IError)
- func NewCSVWriter[T any](w io.Writer, opts ...CSVOptions) (*CSVWriter[T], IError)
- func NewCache(env IENV, opts ...CacheOption) (ICache, IError)
- func NewEnv() (IENV, IError)
- func NewEnvPath(path string) (IENV, IError)
- func NewGormLogger(log ILogger, level gormlogger.LogLevel, slowQuery time.Duration) gormlogger.Interface
- func NewMQ(env IENV, opts ...MQOption) (IMQ, IError)
- func NewMailTemplates(fsys fs.FS, opts ...MailTemplateOptions) (*MailTemplates, IError)
- func NewMailer(env IENV, opts ...MailerOption) (IMailer, IError)
- func NewModules(mods ...IModule) (*ModuleSet, IError)
- func NewMongoDB(env IENV, opts ...MongoOption) (IMongoDB, IError)
- func NewMongoMonitor(log ILogger, level MongoLogLevel, slowQuery time.Duration) *event.CommandMonitor
- func NewMongoPoolMonitor(log ILogger, level MongoLogLevel) *event.PoolMonitor
- func NewMongoServerMonitor(log ILogger, level MongoLogLevel) *event.ServerMonitor
- func NewPusher(credentialJSON string, opts ...PusherOption) (IPusher, IError)
- func NewPusherFromEnv(env IENV, opts ...PusherOption) (IPusher, IError)
- func NewRecordingSentry(env IENV, opts ...SentryOptions) (ISentry, *SentryRecorder, IError)
- func NewRedisLimiter(app *App, opts ...LimiterOption) (ILimiter, IError)
- func NewScheduler(app *App, opts ...SchedulerOption) (*Scheduler, IError)
- func NewSentry(env IENV, opts ...SentryOptions) (ISentry, IError)
- func NewStorage(env IENV, opts ...StorageOption) (IStorage, IError)
- func ParseOrderBy(s string, allowed []string) []string
- func PushTopicTokens(p IPusher, topic string) []string
- func QueueLLMReply(l ILLM, replies ...MemoryLLMReply)
- func Recover(dst *error)
- func RegisterHealthRoutes(e *Server, opts ...HealthOptions)
- func RequestID(ctx context.Context) string
- func Requeue(err error) error
- func ResetChatMessages(c IChat)
- func ResetLLM(l ILLM)
- func ResetMail(m IMailer)
- func ResetPushes(p IPusher)
- func RootCause(err error) error
- func StartHTTPServer(e *Server, env IENV)
- func WithHTTPContext(app *App, h HandlerFunc) echo.HandlerFunc
- func WithRequestID(ctx context.Context, id string) context.Context
- type AckFunc
- type App
- func (a *App) Cache(name ...string) ICache
- func (a *App) Capabilities() []Capability
- func (a *App) Chat(name ...string) IChat
- func (a *App) Config() *ENVConfig
- func (a *App) ENV() IENV
- func (a *App) LLMModel() ILLM
- func (a *App) Log() ILogger
- func (a *App) LogCapabilities()
- func (a *App) MQ() IMQ
- func (a *App) Mailer() IMailer
- func (a *App) Meter() IMeter
- func (a *App) NewContext(ctx context.Context, mode ...Mode) IContext
- func (a *App) NewMQConsumer(opts ...MQConsumerOption) IMQConsumer
- func (a *App) NewSubscriber(opts ...SubscriberOption) ISubscriber
- func (a *App) PubSub() IPubSub
- func (a *App) Pusher() IPusher
- func (a *App) Sentry() ISentry
- func (a *App) Shutdown(ctx context.Context) IError
- func (a *App) Storage() IStorage
- type Attachment
- type Auth
- type AuthOption
- type BackoffFunc
- type BatchResult
- type Breadcrumb
- type CSVOptions
- type CSVWriter
- type CacheOption
- type Capability
- type CaptureOption
- func CaptureContext(name string, data map[string]any) CaptureOption
- func CaptureExtra(key string, value any) CaptureOption
- func CaptureFingerprint(parts ...string) CaptureOption
- func CaptureLevel(l Level) CaptureOption
- func CaptureTag(key, value string) CaptureOption
- func CaptureTags(tags map[string]string) CaptureOption
- type ChatField
- type ChatLevel
- type ChatLink
- type ChatMessage
- type ChatResult
- type CheckIn
- type CheckInStatus
- type CheckResult
- type ConcurrencyPolicy
- type ConsumeQueue
- type ContextUser
- type DBOption
- type Delivery
- type ENVConfig
- type EmailAddress
- type EmailMessage
- type EmailPriority
- type EmbedRequest
- type EmbedTask
- type Error
- func ErrJobRunNotFound(id string) *Error
- func From(err error) *Error
- func InternalServerError() *Error
- func New(status int, code string, message string) *Error
- func Newf(status int, code string, format string, args ...interface{}) *Error
- func Wrap(err error, message string) *Error
- func Wrapf(err error, format string, args ...interface{}) *Error
- func (e *Error) Error() string
- func (e *Error) EventID() string
- func (e *Error) GetCode() string
- func (e *Error) GetMessage() interface{}
- func (e *Error) GetStatus() int
- func (e *Error) Is(target error) bool
- func (e *Error) JSON() interface{}
- func (e *Error) OriginalError() error
- func (e *Error) StackString() string
- func (e *Error) StackTrace() []uintptr
- func (e *Error) Unwrap() error
- func (e *Error) WithCause(cause error) *Error
- func (e *Error) WithCode(code string) *Error
- func (e *Error) WithData(data interface{}) *Error
- func (e *Error) WithFields(fields interface{}) *Error
- func (e *Error) WithMessage(message interface{}) *Error
- func (e *Error) WithStatus(status int) *Error
- type ExchangeConfig
- type Group
- func (g *Group) App() *App
- func (g *Group) DELETE(path string, h HandlerFunc, m ...echo.MiddlewareFunc) echo.RouteInfo
- func (g *Group) Echo() *echo.Group
- func (g *Group) GET(path string, h HandlerFunc, m ...echo.MiddlewareFunc) echo.RouteInfo
- func (g *Group) Group(prefix string, m ...echo.MiddlewareFunc) *Group
- func (g *Group) PATCH(path string, h HandlerFunc, m ...echo.MiddlewareFunc) echo.RouteInfo
- func (g *Group) POST(path string, h HandlerFunc, m ...echo.MiddlewareFunc) echo.RouteInfo
- func (g *Group) PUT(path string, h HandlerFunc, m ...echo.MiddlewareFunc) echo.RouteInfo
- func (g *Group) Use(m ...echo.MiddlewareFunc)
- type HTTPOptions
- type HandlerFunc
- type HealthCheck
- type HealthOptions
- type HealthReport
- type ICache
- type IChat
- type IContext
- type ICronModule
- type ICronjobContext
- type IDocument
- type IENV
- type IEmbedder
- type IError
- func BindDelivery[T any](d *Delivery) (T, IError)
- func BindMessage[T any](m *PubSubMessage) (T, IError)
- func CSVEach[T any](r io.Reader, fn func(T) error, opts ...CSVOptions) IError
- func CSVMarshal[T any](w io.Writer, rows []T, opts ...CSVOptions) IError
- func CSVUnmarshal[T any](r io.Reader, opts ...CSVOptions) ([]T, IError)
- func ChatDisabledError() IError
- func EmbedUnsupportedError(provider, feature string) IError
- func GetJSON[T any](c ICache, key string) (T, IError)
- func GetJSONMany[T any](c ICache, keys ...string) (map[string]T, IError)
- func InstrumentGorm(db *gorm.DB, opts ...SentryGormOptions) IError
- func JWTSign(claims jwt.Claims, secret string) (string, IError)
- func JWTVerify(tokenString string, secret string, dest jwt.Claims) IError
- func LLMDisabledError() IError
- func LLMUnsupportedError(provider, feature string) IError
- func MongoEach[T any](ctx context.Context, cur *mongo.Cursor, fn func(T) error) IError
- func MongoObjectID(id string) (bson.ObjectID, IError)
- func NewDatabase(env IENV, opts ...DBOption) (*gorm.DB, IError)
- func PublishAs[T any](mq IMQ, exchange, key string, msg T) IError
- func RegisterJob[P any](r *JobRegistry, def JobDef, fn func(c ICronjobContext, params P) error) IError
- func Remember[T any](c ICache, key string, ttl time.Duration, load func() (T, error)) (T, IError)
- func RememberOnce[T any](c ICache, key string, ttl, wait time.Duration, load func() (T, error)) (T, IError)
- func SetJSON[T any](c ICache, key string, v T, ttl time.Duration) IError
- func SignJWT(secret string, claims jwt.MapClaims, ttl time.Duration) (string, IError)
- func ValidateChatMessage(msg ChatMessage) IError
- func WithLock(c ICache, key string, ttl time.Duration, fn func() error) IError
- type IFieldSourced
- type IHTTPContext
- type IHTTPModule
- type IHealthModule
- type IJobModule
- type IJobQueue
- type IJobStore
- type ILLM
- type ILifecycleModule
- type ILimiter
- type ILock
- type ILogger
- type IMQ
- type IMQConsumer
- type IMQContext
- type IMQModule
- type IMailer
- type IMeter
- type IModel
- type IModule
- type IMongoDB
- type IParamsDescriber
- type IPubSub
- type IPusher
- type IRequester
- type ISentry
- type ISpan
- type IStorage
- type IStoreBackedQueue
- type ISubscriber
- type ISubscription
- type IValidate
- type IValidateContext
- type JobDef
- type JobFunc
- type JobInfo
- type JobLog
- type JobRegistry
- func (r *JobRegistry) Def(name string) (JobDef, bool)
- func (r *JobRegistry) Info() []JobInfo
- func (r *JobRegistry) IsPaused(name string) bool
- func (r *JobRegistry) List() []JobDef
- func (r *JobRegistry) Params(name string) []ParamField
- func (r *JobRegistry) Pause(name string) IError
- func (r *JobRegistry) Register(def JobDef, fn JobFunc) IError
- func (r *JobRegistry) Resume(name string) IError
- type JobRun
- type JobRunFilter
- type JobRunner
- func (r *JobRunner) Cancel(ctx context.Context, runID, by, reason string) IError
- func (r *JobRunner) Logs(ctx context.Context, runID string, afterSeq int64, limit int) ([]JobLog, IError)
- func (r *JobRunner) NextRun(name string) (time.Time, bool)
- func (r *JobRunner) Pause(name string) IError
- func (r *JobRunner) Purge(ctx context.Context) (int64, IError)
- func (r *JobRunner) Registry() *JobRegistry
- func (r *JobRunner) Replay(ctx context.Context, runID string, opts ...ReplayOptions) (*JobRun, IError)
- func (r *JobRunner) Resume(name string) IError
- func (r *JobRunner) Run(ctx context.Context, id string) (*JobRun, IError)
- func (r *JobRunner) Runs(ctx context.Context, f JobRunFilter) (*Page[JobRun], IError)
- func (r *JobRunner) Scheduled() bool
- func (r *JobRunner) Start()
- func (r *JobRunner) Stop(ctx context.Context) IError
- func (r *JobRunner) Store() IJobStore
- func (r *JobRunner) TailLogs(runID string) (<-chan JobLog, func())
- func (r *JobRunner) Trigger(ctx context.Context, name string, params any, opts ...TriggerOptions) (*JobRun, IError)
- func (r *JobRunner) TriggerAndWait(ctx context.Context, name string, params any, opts ...TriggerOptions) (*JobRun, IError)
- func (r *JobRunner) Wait(ctx context.Context, runID string) (*JobRun, IError)
- type JobRunnerOption
- func WithJobLimiter(l ILimiter) JobRunnerOption
- func WithJobQueue(q IJobQueue) JobRunnerOption
- func WithJobStore(s IJobStore) JobRunnerOption
- func WithLogLimits(l LogLimits) JobRunnerOption
- func WithLogPolicy(p LogPolicy) JobRunnerOption
- func WithQueueLimit(queue string, limit int) JobRunnerOption
- func WithQueues(names ...string) JobRunnerOption
- func WithSlotBackoff(d time.Duration) JobRunnerOption
- func WithWorkerID(id string) JobRunnerOption
- func WithWorkers(n int) JobRunnerOption
- type LLMCapabilities
- type LLMFinishReason
- type LLMMessage
- type LLMPart
- type LLMPartType
- type LLMReasoning
- type LLMRequest
- type LLMResponse
- type LLMRole
- type LLMSchema
- type LLMSource
- type LLMStream
- type LLMTool
- type LLMToolApprover
- type LLMToolCall
- type LLMToolOutcome
- type LLMToolResult
- type LLMUsage
- type Level
- type LimiterOption
- type LogEntry
- type LogLimits
- type LogPolicy
- type LogTapFunc
- type MQConsumerOption
- type MQHandler
- type MQOption
- type MailTemplateOptions
- type MailTemplates
- type MailerOption
- func WithMailAuth(a mail.SMTPAuthType) MailerOption
- func WithMailClientOptions(opts ...mail.Option) MailerOption
- func WithMailHELO(name string) MailerOption
- func WithMailTLSConfig(t *tls.Config) MailerOption
- func WithMailTLSPolicy(p mail.TLSPolicy) MailerOption
- func WithMailTemplates(t *MailTemplates) MailerOption
- func WithMailTimeout(d time.Duration) MailerOption
- type MemoryLLMReply
- type MetricOption
- type Mode
- type ModuleReport
- type ModuleSet
- func (s *ModuleSet) HealthChecks() []HealthCheck
- func (s *ModuleSet) MountConsumers(c IMQConsumer)
- func (s *ModuleSet) MountCron(sc *Scheduler) IError
- func (s *ModuleSet) MountHTTP(e *Server)
- func (s *ModuleSet) MountJobs(reg *JobRegistry) IError
- func (s *ModuleSet) Names() []string
- func (s *ModuleSet) Report() []ModuleReport
- func (s *ModuleSet) Start(app *App) IError
- func (s *ModuleSet) Stop(ctx context.Context) IError
- type MongoAggregateOptions
- type MongoBulkResult
- type MongoFindModifyOptions
- type MongoFindOptions
- type MongoIndex
- type MongoLogLevel
- type MongoOption
- func WithMongoLogLevel(level MongoLogLevel) MongoOption
- func WithMongoLogger(l ILogger) MongoOption
- func WithMongoMonitor(monitor *event.CommandMonitor) MongoOption
- func WithMongoPoolMonitor(monitor *event.PoolMonitor) MongoOption
- func WithMongoServerMonitor(monitor *event.ServerMonitor) MongoOption
- func WithMongoSlowQuery(d time.Duration) MongoOption
- type MongoUpdateOptions
- type MongoUpdateResult
- type Option
- func WithCache(name string, c ICache) Option
- func WithChat(name string, c IChat) Option
- func WithEmbedder(e IEmbedder) Option
- func WithLLM(l ILLM) Option
- func WithLogTap(tap LogTapFunc) Option
- func WithLogger(l ILogger) Option
- func WithMQ(mq IMQ) Option
- func WithMailer(m IMailer) Option
- func WithMongo(name string, m IMongoDB) Option
- func WithPusher(p IPusher) Option
- func WithRequester(r IRequester) Option
- func WithSQL(name string, db *gorm.DB) Option
- func WithSentry(s ISentry) Option
- func WithStorage(s IStorage) Option
- type Page
- type PageOptions
- type ParamField
- type ParamKind
- type ParamOption
- type ParamSpec
- func AnyParam(name string) *ParamSpec
- func ArrayParam(name string, item *ParamSpec) *ParamSpec
- func BoolParam(name string) *ParamSpec
- func CustomParam(name string, kind ParamKind) *ParamSpec
- func DateParam(name string) *ParamSpec
- func DateTimeParam(name string) *ParamSpec
- func EnumParam(name string, values ...string) *ParamSpec
- func IntParam(name string) *ParamSpec
- func NumberParam(name string) *ParamSpec
- func ObjectParam(name string, fields ...*ParamSpec) *ParamSpec
- func StringParam(name string) *ParamSpec
- func TimeParam(name string) *ParamSpec
- func (s *ParamSpec) Between(min, max float64) *ParamSpec
- func (s *ParamSpec) Build() ParamField
- func (s *ParamSpec) Default(value string) *ParamSpec
- func (s *ParamSpec) Desc(description string) *ParamSpec
- func (s *ParamSpec) Enum(values ...string) *ParamSpec
- func (s *ParamSpec) Example(value string) *ParamSpec
- func (s *ParamSpec) Kind(kind ParamKind) *ParamSpec
- func (s *ParamSpec) Label(label string) *ParamSpec
- func (s *ParamSpec) Max(v float64) *ParamSpec
- func (s *ParamSpec) Meta(key string, value any) *ParamSpec
- func (s *ParamSpec) Min(v float64) *ParamSpec
- func (s *ParamSpec) Multiline() *ParamSpec
- func (s *ParamSpec) Options(options ...ParamOption) *ParamSpec
- func (s *ParamSpec) Pattern(expr string) *ParamSpec
- func (s *ParamSpec) Required() *ParamSpec
- func (s *ParamSpec) With(fn func(*ParamField)) *ParamSpec
- type PubSubHandler
- type PubSubMessage
- type PublishOptions
- type PushMessage
- type PushPriority
- type PushResult
- type PusherOption
- type QueueConfig
- type QueueInfo
- type ReplayOptions
- type RunError
- type RunStatus
- type Runner
- type RunnerOption
- func AfterStop(fn func()) RunnerOption
- func BeforeStop(fn func(context.Context) error) RunnerOption
- func RunHTTP(e *Server) RunnerOption
- func RunJobs(j *JobRunner) RunnerOption
- func RunMQ(c ...IMQConsumer) RunnerOption
- func RunModules(set *ModuleSet) RunnerOption
- func RunScheduler(sc *Scheduler) RunnerOption
- func RunService(s ...RunnerService) RunnerOption
- func WithCloseTimeout(d time.Duration) RunnerOption
- func WithDrainTimeout(d time.Duration) RunnerOption
- type RunnerService
- type Schedule
- type Scheduler
- func (sc *Scheduler) Add(def JobDef, fn JobFunc) IError
- func (sc *Scheduler) AddByCron(name, cronExpr string, fn JobFunc) IError
- func (sc *Scheduler) AddByDuration(name string, d time.Duration, fn JobFunc) IError
- func (sc *Scheduler) Runner() *JobRunner
- func (sc *Scheduler) Start() IError
- func (sc *Scheduler) Stop() IError
- type SchedulerOption
- type SentPush
- type SentryGormOptions
- type SentryOptions
- type SentryRecorder
- func (r *SentryRecorder) Close()
- func (r *SentryRecorder) Codes() []string
- func (r *SentryRecorder) Configure(sentry.ClientOptions)
- func (r *SentryRecorder) Errors() []*sentry.Event
- func (r *SentryRecorder) Events() []*sentry.Event
- func (r *SentryRecorder) Flush(time.Duration) bool
- func (r *SentryRecorder) FlushWithContext(context.Context) bool
- func (r *SentryRecorder) HasBreadcrumb(substr string) bool
- func (r *SentryRecorder) HasLog(substr string) bool
- func (r *SentryRecorder) Last() *sentry.Event
- func (r *SentryRecorder) Len() int
- func (r *SentryRecorder) Logs() []sentry.Log
- func (r *SentryRecorder) Metric(name string) *sentry.Metric
- func (r *SentryRecorder) Metrics() []sentry.Metric
- func (r *SentryRecorder) Reset()
- func (r *SentryRecorder) SendEvent(event *sentry.Event)
- type Server
- func (s *Server) App() *App
- func (s *Server) DELETE(path string, h HandlerFunc, m ...echo.MiddlewareFunc) echo.RouteInfo
- func (s *Server) GET(path string, h HandlerFunc, m ...echo.MiddlewareFunc) echo.RouteInfo
- func (s *Server) Group(prefix string, m ...echo.MiddlewareFunc) *Group
- func (s *Server) HandlerNames() map[string]string
- func (s *Server) PATCH(path string, h HandlerFunc, m ...echo.MiddlewareFunc) echo.RouteInfo
- func (s *Server) POST(path string, h HandlerFunc, m ...echo.MiddlewareFunc) echo.RouteInfo
- func (s *Server) PUT(path string, h HandlerFunc, m ...echo.MiddlewareFunc) echo.RouteInfo
- func (s *Server) Serve(ctx context.Context, cfg echo.StartConfig) error
- func (s *Server) Shutdown(ctx context.Context) error
- type Stoppable
- type StorageListOptions
- type StorageObject
- type StorageOption
- type StoragePresignOptions
- type StoragePutOptions
- type SubscriberOption
- type TokenVerifier
- type Trigger
- type TriggerOptions
- type UserResolver
Constants ¶
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) )
const ( DriverPostgres = "postgres" DriverMySQL = "mysql" DriverSQLServer = "sqlserver" DriverOracle = "oracle" )
SQL driver identifiers.
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.
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.
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.
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.
const ( ExchangeDirect = "direct" ExchangeFanout = "fanout" ExchangeTopic = "topic" ExchangeHeaders = "headers" )
Exchange kinds.
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.
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.
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.
const ( LevelDebug = sentry.LevelDebug LevelInfo = sentry.LevelInfo LevelWarning = sentry.LevelWarning LevelError = sentry.LevelError LevelFatal = sentry.LevelFatal )
const ( CheckInProgress = sentry.CheckInStatusInProgress CheckInOK = sentry.CheckInStatusOK CheckInError = sentry.CheckInStatusError )
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.
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).
const DefaultCSVTimeLayout = time.RFC3339
DefaultCSVTimeLayout is how time values are written and read.
const DefaultGracefulTimeout = 10 * time.Second
DefaultGracefulTimeout bounds how long in-flight requests have to finish once a shutdown signal arrives.
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.
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.
const DefaultMailTimeout = 30 * time.Second
DefaultMailTimeout bounds one delivery, connection included.
const DefaultPushTimeout = 15 * time.Second
DefaultPushTimeout bounds one send.
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.
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
},
})
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 ¶
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).
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.
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).
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.
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).
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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).
var ErrPushDisabled = errors.New("push: not configured")
ErrPushDisabled is wrapped by the error every operation returns when no Firebase credentials are configured.
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)
}
var ErrQueueClosed = New(http.StatusServiceUnavailable, "QUEUE_CLOSED", "job queue is closed")
ErrQueueClosed is returned by a closed queue.
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.
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 CosineSimilarity ¶
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 ¶
EmbeddedTexts returns what a memory embedder was asked to embed, in order. It returns nil for any other embedder.
func Forget ¶
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 LockWait ¶
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 ¶
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 ¶
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 NewCSVWriter ¶
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 ¶
NewEnv loads configuration from the current directory (.env, or test.env when APP_ENV=test) plus APP_-prefixed environment variables.
func NewEnvPath ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ResetPushes ¶
func ResetPushes(p IPusher)
ResetPushes drops everything a memory pusher recorded, subscriptions included.
func RootCause ¶
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 ¶
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 ¶
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 ¶
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 ¶
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) LLMModel ¶
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) 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 ¶
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 ¶
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 ¶
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 ¶
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) Pusher ¶
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 ¶
Sentry returns the process-wide error tracker. Prefer ctx.Sentry(), which is bound to the request or run and therefore reports far more context.
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.
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 ¶
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 ¶
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()
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 )
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 ¶
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 ¶
WithDBLogger sends SQL to a specific logger instead of one built from config.
func WithMaxIdleConns ¶
WithMaxIdleConns sets the max idle connections.
func WithMaxOpenConns ¶
WithMaxOpenConns sets the max open connections.
func WithSlowQuery ¶
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 ¶
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) HeaderString ¶
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 ¶
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 ¶
ErrJobRunNotFound is returned when a run id does not exist.
func From ¶
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 ¶
New builds an *Error with the given status, code and message, capturing the call site for the stack trace.
func Newf ¶
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 ¶
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 (*Error) EventID ¶
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) GetMessage ¶
func (e *Error) GetMessage() interface{}
func (*Error) Is ¶
Is reports whether target is an *Error with the same code, so sentinels can be matched with errors.Is regardless of wrapping.
func (*Error) OriginalError ¶
OriginalError returns the wrapped cause, or the error itself when there is none (matching v1 semantics).
func (*Error) StackString ¶
StackString renders the captured call stack as "func\n\tfile:line" frames.
func (*Error) StackTrace ¶
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) WithCause ¶
WithCause returns a copy wrapping cause (for errors.Is / errors.As chains).
func (*Error) WithFields ¶
WithFields returns a copy carrying validation/detail fields.
func (*Error) WithMessage ¶
WithMessage returns a copy with a different message.
func (*Error) WithStatus ¶
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) DELETE ¶
func (g *Group) DELETE(path string, h HandlerFunc, m ...echo.MiddlewareFunc) echo.RouteInfo
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
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 ¶
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 ¶
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.
type ICronModule ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 GetJSONMany ¶
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 ¶
JWTSign signs claims with HS256 using secret. claims is any jwt.Claims implementation (e.g. jwt.RegisteredClaims or a struct embedding it).
func JWTVerify ¶
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 ¶
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 ¶
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 ¶
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 ¶
NewDatabase opens a GORM connection from configuration. The driver is taken from DB_DRIVER, or detected from the connection string's scheme.
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 ¶
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 SignJWT ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
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.
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 ¶
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 ¶
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 ¶
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 ¶
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.
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 (*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.
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).
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 ¶
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 ¶
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) Purge ¶
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) Scheduled ¶
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 ¶
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) TailLogs ¶
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).
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 (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 LLMImageURL ¶
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.
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 ¶
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 ¶
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.
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 ¶
LogPolicyPtr is a helper for the pointer fields on JobDef/TriggerOptions.
type LogTapFunc ¶
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 ¶
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 ¶
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.
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.
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 ¶
MountCron arms every module's scheduled jobs on sc. Mounting the same scheduler twice is a no-op.
func (*ModuleSet) MountHTTP ¶
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) Report ¶
func (s *ModuleSet) Report() []ModuleReport
Report is what each module registered, ordered by declaration.
func (*ModuleSet) Start ¶
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.
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 ¶
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 WithChat ¶
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 ¶
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 ¶
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 WithMailer ¶
WithMailer registers the mailer. Pass NewMemoryMailer() in a test to assert on what a service would have sent.
func WithPusher ¶
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 WithSentry ¶
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.
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 ¶
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.
type PageOptions ¶
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 ¶
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 ArrayParam ¶
ArrayParam declares a list. item describes one element; its name is ignored.
func CustomParam ¶
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 DateTimeParam ¶
DateTimeParam declares an instant (RFC3339).
func NumberParam ¶
NumberParam declares a decimal parameter.
func ObjectParam ¶
ObjectParam declares a nested object with its own fields.
func StringParam ¶
StringParam declares a free-text parameter.
func (*ParamSpec) Meta ¶
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) 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) Required ¶
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 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.
func (RunStatus) IsTerminal ¶
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
- stop taking new work — refuse new connections, stop the cron ticking, stop pulling from the queue
- let the work in flight finish, up to a deadline
- 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 ¶
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 ¶
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.
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 ¶
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 ¶
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 ¶
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 ¶
CronWithSeconds schedules on a 6-field expression whose first field is seconds.
func CronWithSecondsIn ¶
CronWithSecondsIn is CronWithSeconds read in loc.
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) AddByCron ¶
AddByCron schedules fn on a cron expression (v1-compatible shorthand).
func (*Scheduler) AddByDuration ¶
AddByDuration schedules fn to run every d (v1-compatible shorthand).
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 ¶
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) 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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 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.
Source Files
¶
- auth.go
- cache.go
- cache_lock.go
- cache_memory.go
- capabilities.go
- chat.go
- context.go
- cronjob.go
- csv.go
- database.go
- database_logger.go
- database_mongo.go
- database_mongo_impl.go
- database_mongo_logger.go
- email.go
- env.go
- error.go
- fcm.go
- health.go
- http_context.go
- http_field_source.go
- http_server.go
- job.go
- job_context.go
- job_limiter.go
- job_limiter_redis.go
- job_log.go
- job_params_schema.go
- job_queue.go
- job_registry.go
- job_runner.go
- job_store.go
- jwt.go
- llm.go
- llm_embed.go
- llm_log.go
- llm_memory.go
- logger.go
- logger_pretty.go
- logger_sql.go
- logger_tap.go
- module.go
- mq.go
- mq_consumer.go
- mq_impl.go
- pagination.go
- pubsub.go
- pubsub_subscriber.go
- recover.go
- requester.go
- requester_log.go
- runner.go
- s3.go
- s3_memory.go
- sentry.go
- sentry_client.go
- sentry_gorm.go
- sentry_http.go
- sentry_job.go
- sentry_log.go
- sentry_memory.go
- sentry_metric.go
- sentry_scrub.go
- sentry_stacktrace.go
- validate.go
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. |
|
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. |