Signals

signals is how the parts of your app tell each other what they noticed, as one small typed envelope that your handlers and playbooks hear. It is free and needs no service.

Each signal has a name, a severity, a subject, a short life and a signature when it crosses instances. Handlers hear it off the request path. A repeat of a live signal folds into the first (its count goes up) instead of making noise. Built-in names cover resources under pressure, a dependency down, an error budget burning, a deploy and an anomaly.

signals:
  keep: 1000
  max-per-minute: 600
  key: secret:MAINSDK_SIGNAL_KEY

import { signals } from "mainsdk";

// one signal per condition, however often it is emitted while live
await signals.emit("app.import_failed", { severity: "high", subject: "import:nightly", data: { rows: 3 } });

signals.on("pressure.*", (s) => console.log(s.name, s.severity, s.trust));

signals:
  driver: builtin

Quick start

import { signals } from "mainsdk";

// one signal per condition, however often it is emitted while live
await signals.emit("app.import_failed", { severity: "high", subject: "import:nightly", data: { rows: 3 } });

signals.on("pressure.*", (s) => console.log(s.name, s.severity, s.trust), { min: "medium" });

use mainsdk::prelude::*;
let app = App::test();
Context::new().tenant("tnt_a").user("u1").scope(async {
app.signals().emit("app.order.paid", "info", serde_json::json!({ "n": 1 })).await?;
assert_eq!(app.signals().list().await?.len(), 1);
Ok::<_, MainError>(())
}).await?;

Configuration

signals:
  keep: 1000                      # recent signals held per instance, 100 to 10,000
  max-per-minute: 600             # per source; over it, emits are dropped and counted
  key: secret:MAINSDK_SIGNAL_KEY  # HMAC key for app-scope signals across instances
  ttl: { default: 5m, max: 24h }

Without key, app-scope signals go unsigned. With a shared broadcast driver (redis) in production, mainsdk check --env prod reports MAIN-SIGNAL-0007 until you set it, because another app on the same store could forge them.

Calls

Only MainSDK emits the built-in names (pressure.high, dependency.degraded, slo.burning, budget.low, anomaly.detected, posture.changed and others). Your names start with app..

What you get

• Signs with HMAC-SHA256 over canonical JSON (RFC 8785) when key is set, and drops an app-scope signal with no signature or a bad one (MAIN-SIGNAL-0004).
• Redacts data like a log record: labelled personal fields, resolved secrets and key formats are removed, and the attribute is named in MAIN-SIGNAL-0002.
• Folds a repeat of a live signal into the first, and delivers again only when the severity rises.
• Runs handlers off the request path, one at a time per handler, at most 1s each (MAIN-SIGNAL-0005), with a queue of 1,000 (MAIN-SIGNAL-0008).
• Costs under 5 microseconds at p99 per emit with no handler.
• Writes each signal to the log, so mainsdk signals reads it from the local event store.

When the app has a security-event feed (securityEvents, the shape of security.on), detections at high or critical become attack.suspected (subject net:<trimmed network> or actor:<keyed hash>, never a raw id or address), secret.rotated becomes key.rotated (subject secret:<NAME>, never the value) and incident.control becomes incident.control (subject incident:<target>). With no feed these three stay unused.

A single serverless app gets instance-scope signals within one invocation only.

Command line

npx mainsdk signals --min medium            # newest first, with count and age
npx mainsdk signals --name "pressure.*" --json
npx mainsdk signals --follow                # keep printing new ones

Helpers for wiring and tests

Errors and checks

• MAIN-SIGNAL-0001: emit refused (name, severity or data).
• MAIN-SIGNAL-0002: a data attribute was dropped as personal or secret.
• MAIN-SIGNAL-0003: a source passed max-per-minute; the rest were dropped.
• MAIN-SIGNAL-0004: an envelope failed verification (unsigned, bad signature, unknown key, stale or future at).
• MAIN-SIGNAL-0005: a handler threw or ran over 1s.
• MAIN-SIGNAL-0006: a signals value is invalid (mainsdk check).
• MAIN-SIGNAL-0007: production shares a broadcast with app-scope signals and has no signals.key (mainsdk check).
• MAIN-SIGNAL-0008: a handler's queue was full; the oldest were dropped.

Each code's cause and fix is in check codes.

Swapping drivers

signals has no driver of its own. Instance-scope signals stay in the process. App-scope signals ride the app's events.broadcast driver, so changing that driver in main.yaml changes how instances hear each other. With a shared driver (redis) in production, set signals.key (MAIN-SIGNAL-0007). A broadcast outage leaves instance-scope signals working, and a dropped broadcast is not retried.

Testing

createTestApp() from the Testing kit runs signals offline with the fake clock and the local broadcast driver, so a test can emit, advance time past a ttl and read the ring with signals.list. Build a bus directly with new Signals(opts) when you need custom wiring.

Next

• Playbooks act on signals.
• Norms record what the app has learned from them.
• Neighbours carry signals between apps on one machine.
• Log holds each signal as a record.