Skip to content
Cache, Storage, Boot

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 WithShutdownTimeout is 30s; non-positive means no limit.
  • Members of a plain NewApplication stop concurrently. Use NewStagedApplication when one task’s Stop tears down something another task still uses (last stage stops first).
  • Close Wire-owned clients (sql.DB, Redis) in AddAfterStop or in the injector cleanup after Run returns.
  • Constructors such as infra/redis.NewClient do not ping. Add AddBeforeStart if startup must fail when the backend is down.
  • task.NewFunc(id, onStart, onStop) builds a task.Task from callbacks for one-off jobs, instead of a dedicated type. A nil callback is a no-op, Stop runs onStop on every call (make it idempotent), and it does not cancel Start’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 duration
  • expiration == 0 — never expires, and clears any existing TTL
  • expiration < 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.

Related

Last updated on