mirrorstack

func AbsorbInfra ¶

func AbsorbInfra()

AbsorbInfra passes EVERY platform infrastructure metric through to the app owner at a price of 0 — compute, egress, storage, AI tokens, and whatever the platform meters next. Use it when your module bills through its OWN meters and adds no infrastructure passthrough on top.

One flag, no metric names: the platform expands the set from its own catalog at publish, so a metric introduced after your module shipped is absorbed without a republish. An explicit ms.Meter("infra.X", ms.Price(n)) is applied after the absorb and wins.

ms.AbsorbInfra()                                       // baseline: all infra at 0
ms.Meter("infra.egress.api.bytes", ms.Price(120_000))  // …except egress

func AppID ¶

func AppID(ctx context.Context) string

AppID returns the current app id from the request context, or "" if no identity is set. It is the inbound twin of WithAppID and the single unspoofable way a handler reads its OWN app.

On every guarded surface the SDK promotes the platform's trusted, dispatch- injected app id into the context identity BEFORE the handler runs — Platform via PlatformAuth, Public via the proxy guard's validated-token path, and Lambda via the typed invoke payload (runtime.InjectResources). So a Public or Platform handler reads its app with:

appID := ms.AppID(r.Context())

Do NOT read the app id from request data (query string, body, path) — those are caller-controlled and forgeable — and do NOT read the auth.HeaderAppID header: the deployed Lambda shim strips it, so header reads silently break deployed (ms-app-modules#30; see the auth.Header* docs). ms.AppID is the trusted source on every path.

func AppRole ¶

func AppRole(ctx context.Context) string

AppRole returns the current user's role in the app from the request context ("admin", "member", or "viewer" — compare against auth.RoleAdmin / auth.RoleMember / auth.RoleViewer), or "" if no identity is set. Identity promotion and the always-the-context-never-the-X-MS-*-headers rule are exactly as documented on ms.UserID. Note: ms.AppRole is a read of WHO the platform says the caller is — for gating routes by role, prefer the declarative RequirePermission middleware:

if ms.AppRole(r.Context()) == auth.RoleAdmin { ... }

"" is a legitimate value: internal/system/cron/task invocations carry no user role. Under the local-dev bypass (no secret configured) it returns the synthetic auth.RoleAdmin.

func Cache ¶

func Cache(ctx context.Context) (cache.Cacher, func(), error)

Cache returns a scoped cache client on the default module.

func Call ¶

func Call(ctx context.Context, targetModuleID, method, path string, body, out any) error

Call makes one server-mediated module-to-module hop through the platform dispatch, scoped to the current app (app id read from ctx via the SDK's auth identity — callers don't pass it). It JSON-marshals body, sends method to the target module's path, and decodes the JSON response into out (pass nil body for GET, nil out to ignore the response). path must include its leading slash and any raw query, e.g. "/internal/users?limit=10".

The caller never holds the callee's credentials: dispatch injects the TARGET module's per-session token + identity before forwarding. Declare the target as a dependency (ms.DependsOn) — inter-module calls without a declared dep are a wiring bug the platform enforces.

Dev/dispatch transport today; prod catalog/Lambda endpoint resolution is the documented #146 seam (see core.resolveCallURL).

func CallDependencyPost ¶

func CallDependencyPost(ctx context.Context, producerRef, path string, body, out any) error

CallDependencyPost sends an actorless POST to a declared dependency's Internal surface. producerRef accepts the same stable ref used by DependsOn.

func CallGet ¶

func CallGet(ctx context.Context, targetModuleID, path string, out any) error

CallGet is Call specialized to GET (no request body) on the default module.

func CallPost ¶

func CallPost(ctx context.Context, targetModuleID, path string, body, out any) error

CallPost is Call specialized to POST with a JSON body on the default module.

func CallWithOptions ¶

func CallWithOptions(ctx context.Context, targetModuleID, method, path string, body, out any, options CallOptions) error

CallWithOptions is Call with opt-in bounded and strict response decoding. A negative MaxResponseBytes is rejected before any network I/O.

func CancelTask ¶

func CancelTask(ctx context.Context, jobID string) error

CancelTask requests monotonic, idempotent cancellation of a local or managed task.

func ContributesTo ¶

func ContributesTo(hostSpec, slot string, payload any)

ContributesTo declares that this module pushes payload into a host module's slot — the contributor side of Provide. hostSpec is an id or id@constraint; see DependsOn for the full syntax. Zero-runtime: it becomes manifest metadata and the platform (CLI in dev) performs registration after app-owner approval.

func Cron ¶

func Cron(name, schedule string, handler http.HandlerFunc)

Cron registers a scheduled job on the default module.

func DB ¶

func DB(ctx context.Context) (db.Querier, func(), error)

DB returns a scoped database connection on the default module.

func DeliveryURL ¶

func DeliveryURL(ctx context.Context, key string, ttl time.Duration) (string, error)

DeliveryURL returns the CDN URL for ONE gated object, with a freshly minted, short-lived delivery credential attached. key is relative to this module's storage prefix (the same key space ms.Storage uses) and must live under ms.GatedKeyPrefix. ttl is a proposal the platform clamps.

Call it only AFTER deciding the viewer is entitled. The module owns that decision — was the credit charged, is the role held — and the platform owns the credential; the signing key never reaches the module.

🔴 An error means NO URL. It never degrades to an unsigned CDN URL: that would serve paywalled bytes to anyone with the link while looking like a working feature, and those URLs end up in viewers' playlists where a rollback cannot reach them.

One mint per call. For many objects under one prefix — a video's segments — use ms.Delivery once and reuse the ticket.

func DependsOn ¶

func DependsOn(spec string, configure ...func(*Need))

DependsOn declares a REQUIRED dependency on the default module. The optional configure callback names what the consumer wants from the dep — relations (n.Table) and events (n.Event). See the core package for the full spec syntax (id or id@constraint).

func DrainAudit ¶

func DrainAudit(ctx context.Context) error

DrainAudit forwards one bounded batch from the current app's durable audit outbox. Tx already attempts this after a successful commit; cron and worker handlers can call DrainAudit to work through older backlog without owning lease, retry, or transport code themselves.

func Emit ¶

func Emit(ctx context.Context, name string, payload any) error

Emit publishes an event to every LIVE module that subscribes to name within the current app, scoped to the current app (app id read from ctx via the SDK's auth identity — callers don't pass it). The SDK wraps payload in the event envelope ({id, name, sourceModuleID, sentAt, payload}) and POSTs it to the platform dispatch event bus, which fans the SAME envelope out to each subscriber session. An empty app-scope context is an error (no panic).

Delivery is AT-LEAST-ONCE and best-effort per subscriber — subscriber handlers (ms.OnEvent) must be idempotent. Declare the event vocabulary with ms.Emits so subscribers can discover it.

Dev/dispatch transport today; prod event-bus endpoint resolution is the documented #146 seam (see core.resolveEventBusURL, mirroring core.resolveCallURL).

func Emits ¶

func Emits(name string)

Emits declares that the default module emits the named event.

func ExposeTable ¶

func ExposeTable(name string)

ExposeTable marks a table in this module's schema as read-only SELECT-eligible for a depending module — the producer side of DependsOn's n.Table. It is a zero-runtime DECLARATION that lands in the manifest under exposes.tables; the platform issues GRANT SELECT after the app owner approves a dependency.

The producer only opts a table IN to being readable — it does NOT decide WHO reads it. The app owner (not the producer) is the trust root and chooses which installed modules may read by approving their dependency. There is intentionally NO consumer allowlist: in a marketplace the consumers are third parties, so a publisher-controlled reader list is the wrong model. v1 is TABLES ONLY, read-only (SELECT). Panics on an empty or invalid table identifier. Call from startup code.

func Init ¶

func Init(cfg Config) error

Init creates the default Module and stores it for the package-level convenience wrappers to dispatch to.

func Internal ¶

func Internal(fn func(r chi.Router))

Internal registers internal-scoped routes on the default module.

func IsPermanent ¶

func IsPermanent(err error) bool

IsPermanent reports whether err contains a permanent task wrapper.

func Log ¶

func Log(ctx context.Context) *slog.Logger

Log returns the request's structured logger, pre-tagged with the trusted app_id / request_id / module_id correlation fields so every line is attributable in the platform Logcat. Prefer it over the standard library `log` for all module logging. Outside a request it returns the process default logger.

ms.Log(r.Context()).Info("user signed in", "provider", "google")

func MCPTool ¶

func MCPTool[In, Out any](name, description string, handler func(ctx context.Context, args In) (Out, error), opts ...MCPToolOption)

MCPTool registers an agent-callable tool on the default module with JSON Schema derived from the type parameters via reflection. Optional MCPToolOptions scope the tool, e.g. ms.ToolPermission("users.read").

func Meter ¶

func Meter(name string, opts ...MetricOption)

Meter DECLARES a usage metric on the default module. Call it ONCE per metric in startup code (exactly like ms.Emits / ms.RegisterPermission) — it registers the metric as a SIDE EFFECT and returns NOTHING. The declaration (kind + unit + price) is recorded in the manifest so the platform's metric catalog is authoritative before any event arrives.

The kind is an OPTION: pass ms.Counter (additive; platform SUMs) or ms.Gauge (absolute level; platform takes MAX or a time-weighted integral). Emit at runtime BY NAME with ms.Record(ctx, name, value) — mirroring ms.Emits/ms.Emit; the platform reads the declared kind from the catalog, so a call site can never mislabel a metric.

Add ms.BySubject to a Gauge when the billing quantity is SUM(MAX(value) per end-user subject), and emit it with RecordObservation. A custom metric MUST pass exactly one kind option. A reserved infra.*/platform.* metric is platform-measured: it may carry ms.Price ONLY (to override the customer passthrough) — passing a kind, aggregation, or unit on it panics, as does a duplicate name, an invalid name, or conflicting kinds.

ms.Meter("orders.placed", ms.Counter, ms.Unit("order"), ms.Price(50_000))
ms.Meter("users.active", ms.Gauge, ms.BySubject, ms.Unit("user"))
ms.Meter("infra.compute.walltime.ms", ms.Price(0)) // absorb platform compute

To absorb EVERY platform infra metric rather than name them one at a time, call AbsorbInfra — a metric name written here is a copy of the platform's catalog and goes stale when the platform renames one.

func ModuleDB ¶

func ModuleDB(ctx context.Context) (db.Querier, func(), error)

ModuleDB returns a connection scoped to the module's shared schema.

func ModuleTx ¶

func ModuleTx(ctx context.Context, fn func(q db.Querier) error) error

ModuleTx runs fn inside a transaction scoped to the module's shared schema.

func Notify ¶

func Notify(ctx context.Context, n Notification) error

Notify sends an in-app notification to the current app's members, scoped to the current app (app id read from ctx via the SDK's auth identity — callers don't pass it). The SDK resolves the Notification's Labels, wraps them in the notification envelope ({id, sentAt, sourceModuleID, title, body, icon, link, audience}) and POSTs it to the platform dispatch notification ingress, which re-derives the sender identity from the live session and writes the notification into the app's feed. An empty app-scope context, an unset Title, or an unknown Audience is an error (no panic).

ms.Notify(r.Context(), ms.Notification{
    Title:    ms.T("notifications.order.placed"),
    Link:     "/orders/42",
    Audience: ms.NotifyAllMembers,
})

Dev/dispatch transport today; prod notification-ingress resolution is the documented #146 seam (see core.resolveNotifyURL, mirroring core.resolveEventBusURL).

func OnEvent ¶

func OnEvent(name string, handler http.HandlerFunc, opts ...OnEventOption)

OnEvent subscribes the default module to an event from another module. Optional cross-module deps can be co-located via OptionalDependOn:

ms.OnEvent("@anna/billing/payment", onPayment,
    ms.OptionalDependOn("@anna/billing@^1", func(n *ms.Need) {
        n.Table("invoices")
    }))

func OnTask ¶

func OnTask(name string, handler TaskHandler, opts ...TaskOption)

OnTask registers a background task handler on the default module.

func Permanent ¶

func Permanent(err error) error

Permanent marks a task failure as non-retryable.

func Platform ¶

func Platform(fn func(r chi.Router))

Platform registers platform-scoped routes on the default module.

func Provide ¶

func Provide[T any](key string)

Provide declares an extension slot others contribute to on the default module. The type parameter T fixes the payload shape — incoming register requests must unmarshal cleanly into T. The SDK auto-mounts:

POST   /__mirrorstack/contrib/<key>/<module-uuid>   register/upsert
DELETE /__mirrorstack/contrib/<key>/<module-uuid>   unregister
GET    /__mirrorstack/contrib/<key>                 list all registered

Each is Internal-scoped (HMAC-gated by the SDK). Host modules that want to expose a Platform-scoped read with permission gating wrap these endpoints in their own handler — see oauth-core's /platform/providers for the pattern.

Panics on duplicate key or before Init — matches RegisterUI / RequirePermission startup-error conventions.

type ProviderContribution struct {
    Name         string `json:"name"`
    Icon         string `json:"icon"`
    LoginPath    string `json:"login_path"`
    CallbackPath string `json:"callback_path"`
}

ms.Provide[ProviderContribution]("providers")

func Public ¶

func Public(fn func(r chi.Router))

Public registers public-scoped routes on the default module.

func Record ¶

func Record(ctx context.Context, name string, value float64) error

Record emits a usage event for the metric DECLARED (via ms.Meter) under name — BY NAME, exactly mirroring ms.Emit. The platform reads the declared kind from its catalog to decide how to aggregate, so the call site never repeats the kind.

Declaration-first: Record returns an error if name was never declared via ms.Meter (fail fast). It also returns an error (never panics) if value is negative or non-finite. A billing failure must NEVER fail the handler — log the error, don't propagate it.

if err := ms.Record(r.Context(), "orders.placed", 1); err != nil {
    log.Printf("meter: %v", err) // don't fail the handler
}

func RecordObservation ¶

func RecordObservation(ctx context.Context, name string, value float64, observation Observation) error

RecordObservation emits a v2 meter observation with a persisted EventID, opaque end-user Subject, bounded diagnostic Metadata, and original OccurredAt. Metrics declared BySubject must use this path. The SDK validates structure and normalizes OccurredAt to UTC; API and Billing authoritatively decide the accepted occurrence window, replay outcome, and billing period.

func RecordWithID ¶

func RecordWithID(ctx context.Context, eventID, name string, value float64) error

RecordWithID emits a usage event with a caller-persisted UUID as its idempotency key. Persist the ID with the billable state change and reuse it across ambiguous delivery retries.

func RegisterMessages ¶

func RegisterMessages(fsys fs.FS, dir string) error

RegisterMessages loads the module's i18n catalogs from fsys/dir (one <locale>.json per file, nested JSON flattened to dotted keys). Call once at startup, typically with a //go:embed of i18n/*.json. These catalogs back the Labels resolved by RegisterPermission and surfaced in the manifest.

//go:embed i18n/*.json
var i18nFS embed.FS
ms.RegisterMessages(i18nFS, "i18n")

func RegisterPermission ¶

func RegisterPermission(name string, opts PermissionOpts)

RegisterPermission declares a module permission ONCE — its default role, custom roles, and resolved i18n Labels/Descriptions — recording it in the manifest. Call at startup (typically a declare/ package) BEFORE the routes that gate on it. First-wins by name. Names are slug-qualified automatically.

import "github.com/mirrorstack-ai/app-module-sdk/roles"
ms.RegisterPermission("users.read", ms.PermissionOpts{
    DefaultRole: roles.Viewer(),
    Label:       ms.T("permissions.users.read"),
})

func RegisterUI ¶

func RegisterUI(ui ModuleUI)

RegisterUI declares the module's UI surface (agent-visible Components plus DefaultPages). Panics on programmer errors (duplicate names, invalid slug, unknown prop type). Last-write-wins.

func RequirePermission ¶

func RequirePermission(name string) func(http.Handler) http.Handler

RequirePermission returns Chi middleware gating a route on a permission previously declared via RegisterPermission, looked up by NAME:

ms.RequirePermission("users.read")

Admin always passes. If the name was never RegisterPermission'd it is registered lazily as admin-only (safe-by-default) with a dev warning.

func RequireStorage ¶

func RequireStorage()

RequireStorage declares that this module needs its per-app object-storage namespace. Call it during startup before Start; the platform vends storage credentials only to modules whose manifest contains this declaration.

func Resolve ¶

func Resolve[T any](id string) (T, bool)

Resolve looks up a typed client registered by another module. v1 stub always returns (zero, false).

func RunTask ¶

func RunTask(ctx context.Context, name string, payload json.RawMessage) (string, error)

RunTask enqueues a task on the default module.

func RunTaskWithIdempotencyKey ¶

func RunTaskWithIdempotencyKey(ctx context.Context, name string, payload json.RawMessage, idempotencyKey string) (string, error)

RunTaskWithIdempotencyKey creates or recovers one logical managed task job. Persist and reuse the UUID when retrying after an ambiguous enqueue result.

func Start ¶

func Start() error

Start boots the default module: validates manifest, opens DB, binds routes, and starts the HTTP server or Lambda handler depending on runtime mode.

func Storage ¶

func Storage(ctx context.Context) (storage.Storer, error)

Storage returns a scoped storage client on the default module.

func Tx ¶

func Tx(ctx context.Context, fn func(q db.Querier) error) error

Tx runs fn inside a per-app transaction on the default module.

func UserID ¶

func UserID(ctx context.Context) string

UserID returns the current user id from the request context, or "" if no identity is set. Together with ms.AppID and ms.AppRole (or auth.Get, which returns the full Identity in one read) it is the ONLY correct way for module code to read the request's identity: always the context, never the auth.HeaderUserID (X-MS-User-ID) header — the deployed Lambda shim strips it, so header reads work under the dev tunnel and silently break deployed (ms-app-modules#30; see the auth.Header* docs).

On every guarded surface the SDK promotes the platform's trusted, dispatch- injected user id into the context identity BEFORE the handler runs — Platform via PlatformAuth, Public via the proxy guard's validated-token path, and Lambda via the typed invoke payload (runtime.InjectResources). So a handler reads the requesting user with:

userID := ms.UserID(r.Context())

"" is a legitimate value, not only an unauthenticated-middleware artifact: internal/system/cron/task invocations carry no user, and an anonymous Public request may carry an identity whose user id is empty. Under the local-dev bypass (no secret configured) it returns the synthetic "local-dev-user".

func WithAppID ¶

func WithAppID(ctx context.Context, appID string) context.Context

WithAppID returns a context whose inter-module Call scope is the given app, overriding the ambient identity's app. ms.Call reads the app id from the context (auth.Get) — for a handler that is the request's authenticated app, so authenticated callers need nothing extra.

Use it to RETARGET an outbound ms.Call at a DIFFERENT app than the ambient one (the rare cross-app proxy case). To read your OWN app id, use ms.AppID — the SDK already promotes the request's trusted app into the identity, so a Public/Platform handler does not need WithAppID just to call within its own app:

ctx = ms.WithAppID(ctx, otherAppID)
ms.CallGet(ctx, providerModuleID, "/internal/authorize-url?"+q, &out)

Any existing UserID/AppRole on the context is preserved; only AppID changes.

func WriteError ¶

func WriteError(w http.ResponseWriter, status int, msg string)

WriteError writes the JSON error envelope {"error": msg} with the given status code, via WriteJSON. Use the canonical ErrorResponse shape rather than an ad-hoc map so module errors match the SDK's own error wire format.

func WriteJSON ¶

func WriteJSON(w http.ResponseWriter, status int, v any)

WriteJSON writes v to w as JSON with the given status code and a Content-Type: application/json header. A nil v writes only the status and header with no body (for 204-style empty responses). An encode error is logged, not returned — the status line is already committed by then.

This is the response writer every module otherwise hand-rolls; it backs the same internal helper the SDK uses for its own endpoints.

func WriteServerError ¶

func WriteServerError(w http.ResponseWriter, r *http.Request, operation string, err error)

WriteServerError logs err with the request's trusted correlation fields and returns a fixed, non-sensitive 500 response. operation is an internal log label; it is never copied to the response. Use this boundary instead of returning err.Error(), which can expose SQL, credentials, or topology.