API

Every exported symbol of github.com/gsandoval/tako, from the same lock file the API-freeze test compares against — so this page cannot quietly lose one. Everything under pkg/… is tako's internals and is not here.

HTTP

tako.API

func API[Req, Res any](route string, fn func(Ctx, Req) (Res, error), cfg ...Route) Endpoint[Req, Res]
func Errorf(status int, format string, args ...any) error
func IsNotFound(err error) bool
func NotFound() error
type Client struct{IP string; UserAgent string}
type Ctx interface{Client() Client; IsHTMX() bool; Log() *log/slog.Logger; MaybeUser() (User, bool); Task() (index int, count int); User() User; context.Context}
func (Ctx).Client() Client
func (Ctx).IsHTMX() bool
func (Ctx).Log() *log/slog.Logger
func (Ctx).MaybeUser() (User, bool)
func (Ctx).Task() (index int, count int)
func (Ctx).User() User
func (context.Context).Deadline() (deadline time.Time, ok bool)
func (context.Context).Done() <-chan struct{}
func (context.Context).Err() error
func (context.Context).Value(key any) any
type Route struct{SignIn bool; Allow *PolicyHandle; Private bool; MaxAge time.Duration}

tako.Page

func Page[Req any](route string, fn func(Ctx, Req) (HTML, error), cfg ...Route) Endpoint[Req, HTML]
func Redirect(target string) (HTML, error)
func RedirectPermanent(target string) (HTML, error)
type HTML struct{}

tako.Site

func Site(dir string, cfg ...SiteConfig) *SiteHandle
func StatusPage(fn func(Ctx, Status) (HTML, error)) StatusHandle
type Build struct{Command string; Out string}
type SiteConfig struct{SPA bool; Build Build; DevProxy string; Redirects map[string]string; TrustedHTML bool; NotFound string}
type SiteHandle struct{}
func (*SiteHandle).Fragment(ctx Ctx, template string, data any) (HTML, error)
func (*SiteHandle).Markdown(ctx Ctx, src string) (HTML, error)
func (*SiteHandle).PrepareTemplates(ctx Ctx, fsys io/fs.FS) (*TemplateSet, error)
func (*SiteHandle).Render(ctx Ctx, template string, data any) (HTML, error)
func (*SiteHandle).UseTemplates(ctx Ctx, set *TemplateSet) error
type Status struct{Code int; Path string; RequestID string; Message string; Policy string}
type StatusHandle struct{}
func (StatusHandle).Declared() bool
func (StatusHandle).Render(ctx Ctx, s Status) (HTML, error)
type TemplateErrors struct{Failed map[string]string}
func (*TemplateErrors).Error() string
type TemplateSet struct{}
func (*TemplateSet).Fragment(ctx Ctx, template string, data any) (HTML, error)
func (*TemplateSet).Render(ctx Ctx, template string, data any) (HTML, error)

tako.Service

const EnvCloud Env
const EnvLocal Env
func Environment() Env
func Service(cfg ...ServiceConfig) *ServiceHandle
type Env int
func (Env).String() string
type ServiceConfig struct{Domain string; Profile Profile; Footprint Footprint; Traffic Traffic}
type ServiceHandle struct{}
func (*ServiceHandle).Domain() string

Data

tako.Entity — typed entity stores

func Entity[T any](name string) *EntityHandle[T]
func NewID() string
type EntityHandle[T any] struct{}
func (*EntityHandle[T]).Delete(ctx Ctx, id string) error
func (*EntityHandle[T]).Exists(ctx Ctx, id string) (bool, error)
func (*EntityHandle[T]).Get(ctx Ctx, id string) (T, error)
func (*EntityHandle[T]).Put(ctx Ctx, entity T) error
func (*EntityHandle[T]).Query(ctx Ctx) *EntityQuery[T]
func (*EntityHandle[T]).Tx(ctx Ctx, fn func(tx EntityTx[T]) error) error
func (*EntityHandle[T]).Update(ctx Ctx, id string, mutate func(*T)) error
type EntityPage[T any] struct{Items []T; Cursor string; More bool}
type EntityQuery[T any] struct{}
func (*EntityQuery[T]).All() ([]T, error)
func (*EntityQuery[T]).Count() (int64, error)
func (*EntityQuery[T]).First() (T, error)
func (*EntityQuery[T]).Iter() Iter[T]
func (*EntityQuery[T]).Limit(n int) *EntityQuery[T]
func (*EntityQuery[T]).OrderBy(field string) *EntityQuery[T]
func (*EntityQuery[T]).Page(cursor string) (EntityPage[T], error)
func (*EntityQuery[T]).Where(field string, op string, value any) *EntityQuery[T]
type EntityTx[T any] interface{Delete(id string) error; Get(id string) (T, error); Put(entity T) error}
func (EntityTx[T any]).Delete(id string) error
func (EntityTx[T any]).Get(id string) (T, error)
func (EntityTx[T any]).Put(entity T) error
type Iter[T any] struct{}
func (*Iter[T]).Err() error
func (*Iter[T]).Next() (T, bool)

tako.Cache — per-instance TTL cache

func Cache[T any](name string, ttl time.Duration) *CacheHandle[T]
type CacheHandle[T any] struct{}
func (*CacheHandle[T]).Delete(ctx Ctx, key string) error
func (*CacheHandle[T]).Exists(ctx Ctx, key string) (bool, error)
func (*CacheHandle[T]).Get(ctx Ctx, key string) (T, error)
func (*CacheHandle[T]).GetOrFill(ctx Ctx, key string, fill func(Ctx) (T, error)) (T, error)
func (*CacheHandle[T]).Put(ctx Ctx, key string, value T) error

tako.Secret, metrics, and tako logs

func Counter(name string) *CounterHandle
func Histogram(name string) *HistogramHandle
func Secret(name string) *SecretHandle
type CounterHandle struct{}
func (*CounterHandle).Add(ctx Ctx, delta int64)
func (*CounterHandle).Count() Metric
func (*CounterHandle).Rate() Metric
type HistogramHandle struct{}
func (*HistogramHandle).Count() Metric
func (*HistogramHandle).Mean() Metric
func (*HistogramHandle).Observe(ctx Ctx, value float64)
func (*HistogramHandle).Percentile(q float64) Metric
func (*HistogramHandle).Rate() Metric
func (*HistogramHandle).Sum() Metric
type SecretHandle struct{}
func (*SecretHandle).Value() string

tako.Alert — conditions, channels, and who gets woken up

func Alert(when Condition, notify *ChannelHandle, also ...*ChannelHandle) AlertHandle
func AlertEmail(address string) *ChannelHandle
func AlertTopic[T any](topic *TopicHandle[T]) *ChannelHandle
func AlertWebhook(url string) *ChannelHandle
func CronFailed(cron Handler, times int, w ...Window) Condition
func CronMissed(cron Handler, w ...Window) Condition
func JobFailed[T any](job *JobHandle[T], times int, w ...Window) Condition
func PlatformMetric(metricType string, filters ...string) Metric
func QueueBacklogged(c Consumer, n int, w QueueWatch) Condition
func QueueMetric(c Consumer, metricType string, filters ...string) Metric
func QueueStalled(c Consumer, age time.Duration, w QueueWatch) Condition
func RequestMs(t Target) *RequestMsHandle
func Requests(t Target) *RequestsHandle
func RequestsErroring(t Target, fraction float64, w ...Window) Condition
func RequestsSlow(t Target, d time.Duration, quantile float64, w ...Window) Condition
func ServiceAtCapacity(t Target, w ...Window) Condition
func ServiceInstances(t Target) Metric
func ServiceMetric(t Target, metricType string, filters ...string) Metric
func ServicePercentile(t Target, metricType string, q float64, filters ...string) Metric
func SingletonDown(loop Handler, w ...Window) Condition
func WhenAbove(m Metric, threshold float64, w Window) Condition
func WhenAbsent(m Metric, w Window) Condition
func WhenAtLeast(m Metric, n float64, w Window) Condition
func WhenBelow(m Metric, threshold float64, w Window) Condition
type AlertHandle struct{}
type ChannelHandle struct{}
type Condition struct{}
type Consumer interface{consumerRef() metricRef}
type Metric interface{metricSubject() metricRef}
type QueueWatch struct{DeadLetters bool; For time.Duration}
type RequestMsHandle struct{}
func (*RequestMsHandle).Count() Metric
func (*RequestMsHandle).Mean() Metric
func (*RequestMsHandle).Percentile(q float64) Metric
func (*RequestMsHandle).Rate() Metric
func (*RequestMsHandle).Sum() Metric
type RequestsHandle struct{}
func (*RequestsHandle).Count() Metric
func (*RequestsHandle).Fraction() Metric
func (*RequestsHandle).Rate() Metric
func (*RequestsHandle).Status(class string) *RequestsHandle
type Target interface{alertTarget() metricRef}
type Window struct{For time.Duration; Every time.Duration}

Async

tako.Queue + tako.Worker — at-least-once work

func Permanent(err error) error
func Queue[T any](name string, cfg ...Delivery) *QueueHandle[T]
func Worker[T any](queue *QueueHandle[T], fn func(Ctx, T) error, cfg ...Compute) Handler
type Delivery struct{MaxAttempts int; MinBackoff time.Duration; MaxBackoff time.Duration; RateLimit int}
type QueueHandle[T any] struct{}
func (*QueueHandle[T]).Publish(ctx Ctx, msg T) error
func (*QueueHandle[T]).PublishAfter(ctx Ctx, msg T, delay time.Duration) error

tako.Topic + tako.Subscribe — fan-out events

func Subscribe[T any](source EventSource[T], fn func(Ctx, T) error, cfg ...Compute) Handler
func Topic[T any](name string, cfg ...Delivery) *TopicHandle[T]
type EventSource[T any] interface{eventSource(T); sourceName() string}
type TopicHandle[T any] struct{}
func (*TopicHandle[T]).Publish(ctx Ctx, event T) error

tako.Bucket — blobs, signed URLs, upload events

func Bucket(name string) *BucketHandle
type Blob struct{Reader io.Reader; ContentType string; Size int64; ETag string}
type BucketEvent struct{}
type BucketHandle struct{Uploaded BucketEvent}
func (*BucketHandle).Delete(ctx Ctx, key string) error
func (*BucketHandle).Exists(ctx Ctx, key string) (bool, error)
func (*BucketHandle).Get(ctx Ctx, key string) (Blob, error)
func (*BucketHandle).List(ctx Ctx, prefix string) Iter[ObjectInfo]
func (*BucketHandle).Put(ctx Ctx, key string, blob Blob) error
func (*BucketHandle).SignedGet(ctx Ctx, key string, ttl time.Duration) (string, error)
func (*BucketHandle).SignedPut(ctx Ctx, key string, ttl time.Duration, policy ...PutPolicy) (string, error)
type ObjectInfo struct{Key string; Size int64; ContentType string; Updated time.Time}
type PutPolicy struct{MaxSize int64; ContentType string}
func (PutPolicy).Headers() map[string]string

tako.Cron — scheduled handlers

func Cron(schedule string, fn func(Ctx) error, cfg ...CronConfig) Handler
type CronConfig struct{Singleflight bool; Timezone string; Deadline time.Duration; Profile Profile; Footprint Footprint}

tako.Lock — distributed leases

func Lock(name string) *LockHandle
type LockHandle struct{}
func (*LockHandle).Do(ctx Ctx, fn func(Ctx) error) error
func (*LockHandle).TryDo(ctx Ctx, fn func(Ctx) error) (bool, error)

tako.Handler — what a background declaration returns

type Handler struct{}

Compute

job.md — tako.Job + tako.Runner

func Job[T any](name string) *JobHandle[T]
func Runner[T any](job *JobHandle[T], fn func(Ctx, T) error, cfg ...RunnerConfig) Handler
type JobHandle[T any] struct{}
func (*JobHandle[T]).Run(ctx Ctx, params T) error
type RunnerConfig struct{Parallel int; Attempts int; Timeout time.Duration; Profile Profile; Footprint Footprint}

singleton.md — tako.Singleton

func Singleton(fn func(Ctx) error, cfg ...SingletonConfig) Handler
type SingletonConfig struct{Timeout time.Duration; Footprint Footprint}

calls.md — cross-service calls

type Endpoint[Req any, Res any] struct{}
func (Endpoint[Req, Res]).Call(ctx Ctx, req Req) (Res, error)

footprint.md — the Profile and Footprint fields

const ProfileBatch Profile
const ProfileDefault Profile
const ProfileLatency Profile
const ToggleInherit Toggle
const ToggleOff Toggle
const ToggleOn Toggle
type Compute struct{Profile Profile; Footprint Footprint; Traffic Traffic}
type Footprint struct{CPU int; Memory string; Concurrency int; MinInstances int; MaxInstances int; CPUAlwaysOn Toggle; StartupBoost Toggle}
type Profile int
type Toggle int
type Traffic struct{Timeout time.Duration; SessionAffinity Toggle; HTTP2 Toggle}

Edges

tako.Auth — providers, sessions, Route.SignIn, the dev bar

func Auth(cfg AuthConfig) *AuthHandle
func Deny(msg string) error
func IsDenied(err error) bool
func IsEmailTaken(err error) bool
func Policy(fn func(Ctx, User) error) *PolicyHandle
func RequireRole(roles ...RoleHandle) *PolicyHandle
func Role(name string) RoleHandle
type AuthConfig struct{Google bool; Password bool}
type AuthEvent struct{}
type AuthHandle struct{Registered AuthEvent; FirstSignIn AuthEvent}
func (*AuthHandle).Users() *UsersHandle
type NewUser struct{Email string; Password string; Name string; Roles []string}
type PolicyHandle struct{}
func (*PolicyHandle).Check(ctx Ctx, u User) error
func (*PolicyHandle).Roles() []string
type RoleHandle struct{}
func (RoleHandle).Name() string
type User struct{ID string; Email string; Name string; Provider string; Roles []string; EmailVerified bool}
func (User).HasRole(role RoleHandle) bool
type UserQuery struct{}
func (*UserQuery).Limit(n int) *UserQuery
func (*UserQuery).Page(cursor string) (UsersPage, error)
type UsersHandle struct{}
func (*UsersHandle).ByEmail(ctx Ctx, email string) (User, error)
func (*UsersHandle).Create(ctx Ctx, spec NewUser) (User, error)
func (*UsersHandle).Delete(ctx Ctx, id string) error
func (*UsersHandle).Disable(ctx Ctx, id string) error
func (*UsersHandle).Enable(ctx Ctx, id string) error
func (*UsersHandle).Get(ctx Ctx, id string) (User, error)
func (*UsersHandle).Grant(ctx Ctx, id string, role RoleHandle) error
func (*UsersHandle).List(ctx Ctx) *UserQuery
func (*UsersHandle).Revoke(ctx Ctx, id string, role RoleHandle) error
type UsersPage struct{Users []User; Next string}

tako.NewTestApp: testing an app

func NewTestApp(tb testing.TB) *TestApp
type TestApp struct{}
func (*TestApp).Advance(d time.Duration)
func (*TestApp).AdvanceCron(cron Handler)
func (*TestApp).Chaos()
func (*TestApp).Ctx(as ...User) Ctx
func (*TestApp).DrainQueues()
func (*TestApp).HTMX(as ...User) Ctx
func (*TestApp).Handler() net/http.Handler
func (*TestApp).SetSecret(name string, value string)
func (*TestApp).SignIn(name string, roles ...RoleHandle) User