Cache, Storage, Boot
Sphere ships small interfaces and default adapters for cache, object storage, messaging, scheduling, and process lifecycle. They are optional. Generated HTTP code does not depend on them.
Boot and tasks
Everything long-running implements core/task.Task (Identifier, Start, Stop). boot.Run wraps a task.Group with OS signals, hooks, and a shutdown deadline.
err := boot.Run(conf, func(c *Conf) (*boot.Application, error) {
return boot.NewApplication(httpTask, consumerTask), nil
}, boot.WithLoggerBackend(backend))- Default
WithShutdownTimeoutis 30s; non-positive means no limit. - Members of a plain
NewApplicationstop concurrently. UseNewStagedApplicationwhen one task’sStoptears down something another task still uses (last stage stops first). - Close Wire-owned clients (
sql.DB, Redis) inAddAfterStopor in the injector cleanup afterRunreturns. - Constructors such as
infra/redis.NewClientdo not ping. AddAddBeforeStartif startup must fail when the backend is down. task.NewFunc(id, onStart, onStop)builds atask.Taskfrom callbacks for one-off jobs, instead of a dedicated type. A nil callback is a no-op,StoprunsonStopon every call (make it idempotent), and it does not cancelStart’s context — the group does.
Cache
cache.Cache[S] is CRUD + batch + TTL + Close. Drivers: memory (ristretto), mcache, redis, badgerdb, nocache. nscache prefixes keys so several logical caches can share one backend.
TTL contract:
expiration > 0— expires after that durationexpiration == 0— never expires, and clears any existing TTLexpiration < 0—cache.ErrInvalidTTL, no write
A constructor that opens a client/DB closes it; a constructor that receives one does not. CodecCache / NSCache Close is a no-op.
DelAll blast radius differs by driver (Redis FLUSHDB of the selected DB, memory/mcache the whole process cache, NSCache only its namespace). Do not share a Redis database with unrelated keys if you call DelAll.
Storage
Drivers: local, s3, qiniu, kvcache. fileserver is an HTTP adapter with one-time upload tokens stored under sphere-upload-token: in its injected cache.ByteCache, not an S3 driver.
Every driver runs storage.NormalizeKey first. Persist the key UploadFile returns. DeleteFile succeeds when the object is already gone. Downloads are served as attachments by default.
server/service/file.NewLocalFileService pairs local storage with an in-memory memory.NewByteCache(), which only works for a single replica (tokens issued by one instance are unknown to another). For multi-replica deployments, pass a shared cache/redis cache and shared storage (s3 or qiniu) to fileserver.NewCDNAdapter.
Scheduler and MQ
scheduler/cron and scheduler/asynq implement task.Task. Start blocks until the run context ends and does not drain; Stop is the cleanup half. For scheduler/asynq, Stop stops the server’s processor first (no new tasks are pulled), then shuts cron down, then drains the server. A panic in any of those steps is returned from Stop (the remaining steps still run) and leaves the scheduler unclosed, so treat the injected Redis client as still in use. If the Stop context expires first, the drain continues in the background: close the Redis client only after Stop returns nil or Close returns. Periodic jobs are not coordinated across processes — run one replica, or make handlers idempotent.
mq provides Queue and PubSub (plus the combined MessageQueue) with memory and redis drivers. PubSub implements task.Task: Stop(ctx) requests shutdown and waits for in-flight subscription handlers to return (or ctx to expire). MessageQueue.Close closes the Queue (redis Queue.Close is a no-op) and calls RequestStop(), which signals stop without waiting for running handlers — use Stop(ctx) (or register it in boot.NewApplication) when you need graceful handler drain. On the Redis driver, neither Stop nor Close closes the injected Redis client.
Search
search defines a typed search.Searcher[T] interface (Index, Delete, Search) backed by search/meilisearch. Params.Filter is passed through verbatim in Meilisearch filter syntax, and Result.Total is an estimate (EstimatedTotalHits, clamped by pagination.maxTotalHits, 1000 by default) — paginate until a page returns fewer hits than requested rather than relying on Total.