Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Upgrading to 0.6.20

2026-11-10. A superseded version now keeps serving the channels only it declares, until it retires, where 0.6.18 and 0.6.19 drained it whole. Another owner is refused such an endpoint until then. A literal local:// send to another package, or to another version of the same package, is refused at lint and deploy. The engine uses about half the CPU it did under load: evaluation no longer copies the variables, and jemalloc is the allocator. Coverage can be checked against requirements, in named compliance cycles. RabbitMQ and AMQP broker credentials accept secret: references. Two additive migrations run at boot: V1003 (deployments) and V904 (coverage, at the store’s next first use). There is no archive format, deploymentId or snapshot format change.

Before you upgrade

Check these against what you run:

  • A q:send to a literal local:// address that is not one of the package’s own transport: local channels. Another package, another version of this package, and a bare local://<name> are now refused by sutra lint, sutra package and every deploy path, with SUTRA.CONFIG.SEND.LOCAL_DESTINATION_CROSSES_PACKAGE. A destination containing ${ is not judged. A stored db deployment with such a send keeps running and logs the error at each load. A file in a deployments folder with one goes Failed at the next scan, including the first boot after the upgrade. Replace the send with an outbound channel the other package listens on.
  • A calledElement, or a <q:dispatch> case or default, that names no process of the package is refused the same way, with SUTRA.CONFIG.CALL_ACTIVITY.UNKNOWN_CALLED_ELEMENT, with the same exemption for stored rows and the same effect on a folder. A calledElement that a <q:dispatch> replaces is never used, so it is not checked.
  • An old version can now hold an endpoint for as long as it has running instances. If you move an endpoint from one module to another (another owner) while the old module’s previous version is draining, the deploy is refused until that version retires. A version with instances parked indefinitely holds its channels indefinitely. /sutra/deployments shows the count under drainingInstances.
  • New traffic can start on the old version after the flip, on the channels it keeps. Moving that traffic to the new version is up to your integration.
  • New warnings. SUTRA.CONFIG.PROPERTY.BLANK_REFERENCE, SUTRA.DEPLOY.ENDPOINT.CHANNEL_CHANGED, SUTRA.DEPLOY.ENDPOINT.START_ON_WAIT and the lint warning SUTRA.CONFIG.CHANNEL.START_AND_WAIT are described below. None of them refuses anything.

Upgrading a deployment in place

When a new version of a tenant and module takes over, the old version drains as before: it takes no new work on the channels the new version has, and its running instances finish on it. New in 0.6.20, an inbound channel that no newer version declares, by name or on any of its endpoints, stays served by the old version, starts included, until the old version retires at zero running instances and zero pending outbox. SUTRA.DEPLOY.ENDPOINT.SUPERSEDED names those endpoints, and the timer starts that stop at the drain:

[WARN] SUTRA.DEPLOY.ENDPOINT.SUPERSEDED — deployment acme--orders--2.0.0 takes over from acme--orders--1.0.0, an earlier deployment of the same tenant and module. acme--orders--1.0.0 drains: it takes no new work, and its running instances finish on it. Channels only it declares stay served by it until it retires: POST /orders/release, POST /orders/legacy.
  • What the old version keeps is recomputed at every change. Undeploying the new version gives the old one back every channel it declares, the ones it shared with the new version included, until it retires; then they stop. Undeploying the old version itself, while it is active, stops them.
  • Retirement is rechecked. A version that just retired is checked again until it is quiet twice; one that had work arrive after all goes back to draining.
  • A version that keeps feeding itself over its own channel never retires. The engine does not stop it. GET /sutra/deployments now shows each draining version’s running instances under drainingInstances ({"<deploymentId>": n}), and GET /sutra/deployments/{id} gains instances for a draining version. The draining array is unchanged.
  • Versions already draining when you upgrade the engine stop serving as before. Only a version superseded on 0.6.20 keeps channels.
  • In a deployments folder, removing the old version’s file stops its channels, and the answer survives a restart.

Another owner is refused an endpoint a draining version keeps, until it retires:

[SUTRA.DEPLOY.ENDPOINT.COLLISION] http endpoint 'POST /orders/release' stays with draining deployment acme--orders--1.0.0 (2 running instances) until it retires

0.6.19 let another owner take it at once. POST /admin/deployments/check gives the same answer.

Upgrade warnings. These name what changes and how many instances are parked on it, and never print an auth value:

  • SUTRA.DEPLOY.ENDPOINT.CHANNEL_CHANGED: the deploy changes a channel an older version has instances parked on: its inbound auth, codec, schema, address or transport, or “renamed or replaced” when its endpoint is now served under another channel name.
  • SUTRA.DEPLOY.ENDPOINT.START_ON_WAIT: a new start event listens where the older version waits. Start events are tried first, so a reply meant for a parked instance starts a new one.
  • SUTRA.CONFIG.CHANNEL.START_AND_WAIT: sutra lint warns about the same shape within one package.

Unchanged: a resume on a channel the new version changed is processed with the new version’s binding; an old instance parked on a channel the new version serves under another name is still unreachable from it (now warned); a retry across a version flip still runs again.

Schema: migration V1003 adds deployment_archive.retains_channels on PostgreSQL, MySQL and SQL Server. It is FALSE for rows drained before it existed.

The walkthrough is Upgrading a deployment in place; One endpoint, one deployment describes how the other deployment paths behave.

Less engine CPU under load

  • Expressions evaluate without copying the variables. A FEEL dotted path walks nested values by reference and copies only the value it ends on. Data tasks, exclusive gateways and q:param inputs evaluate against the live variables, and each operation still sees the previous one’s result. A strict template engine gets a render model built without null entries in one pass, with the same JSON and key order.
  • jemalloc is the engine’s allocator. It is a default feature, jemalloc, of sutra-dist, and is never linked on MSVC targets. A build with --no-default-features drops it, along with the other defaults, and uses the system allocator. jemalloc fixes its page size when it is built: an arm64 image build sets JEMALLOC_SYS_WITH_LG_PAGE=16 (64 KiB), so the binary also runs on kernels with 16 or 64 KiB pages. If you build your own arm64 binary, set it too, or the binary aborts at start on such a kernel. amd64 is unaffected.
  • Measured on a laptop at 200 messages/s for 60 s, every message completed, none duplicated: steady engine CPU fell from about 316% to about 139% of one core, roughly 42% from the evaluation change and a further 24% from jemalloc. With database writes off, 267% to 121%. jemalloc used less CPU than mimalloc and had the lower p99. The runs were bound by the laptop’s disk, so their latencies are only indicative; the CPU figures are the reliable ones. A relay benchmark at 500 messages/s showed no change.

Coverage against requirements, in compliance cycles

The walkthrough is in Coverage.

  • A requirements map. A package can ship coverage/requirements-map.yaml, mapping each declared path to requirement ids, a weight (default 1, above zero) and the test cases that walk it. sutra coverage check then adds a compliance object: per-requirement and weighted percentages, uncovered paths with their cases, the cases to run, and paths with no cases or no mapping. --threshold gates the weighted percentage. Every declared path counts; there is no way to exclude one. A package with no map reports as before. Lint: SUTRA.CONFIG.COVERAGE.MAPPING_ROUTE_UNKNOWN (error, a key that matches no declared path) and SUTRA.CONFIG.COVERAGE.MAPPING_ROUTE_UNMAPPED (warning, a declared path the map leaves out, counted at weight 1).
  • Cycles. sutra coverage cycle declare|activate|deactivate <LABEL> and sutra coverage cycle list, plus --cycle on coverage check and coverage reset. While a cycle is active, every mark for that deployment records to it, including the coverage:report and coverage:reset operations. A mark belongs to the cycle active when its instance completes. One cycle can be active per deployment: a second activation is refused (SUTRA.RUNTIME.COVERAGE.CYCLE_ALREADY_ACTIVE), as is activating an undeclared label (CYCLE_UNDECLARED); reactivating a cycle continues it. With none active, coverage records as before, and check and reset without --cycle read the marks recorded outside any cycle. Cycles belong to a deployment id, so a changed package starts with none. The sutra.coverage.percent gauge and the path counter are not cycle-aware.
  • To re-run a case, send <cycle>:<case>:<attempt> as the idempotency key on a channel that declares idempotency-key-header: a repeat of an attempt does nothing, the next attempt runs.
  • Schema: V904 adds four coverage tables (coverage_cycle, coverage_active_cycle, coverage_cycle_metric, coverage_cycle_fragment) on PostgreSQL, MySQL/MariaDB and SQL Server. Existing rows are untouched and read as “no cycle”.

Connection references

See References in connection properties.

  • RabbitMQ and AMQP broker credentials accept secret:KEY and ${secret:KEY}. username and password now take exactly the whole-value forms the reference resolver resolves, plus k8s:secret/<name>#<key>. 0.6.19 refused the two secret: forms there. A literal, or text with a reference inside it such as pre${X}, is still refused with SUTRA.STARTUP.REFUSED.HARDCODED_SECRET.
  • RabbitMQ now accepts a lowercase ${name} in credentials, as AMQP already did. It used to refuse it.
  • A reference that resolves to blank now warns SUTRA.CONFIG.PROPERTY.BLANK_REFERENCE, naming the channel, the property and the reference as written, never a value. 0.6.19 applied the transport’s default silently: RabbitMQ host became localhost, Kafka group.id became sutra-<channel>. That still happens, and a blank required property is still refused, now after the warning. The explicit-empty forms ${NAME:} and ${secret:KEY:} do not warn, so write an optional setting that way. This covers the connection properties of kafka, rabbitmq, amqp, gcp-pubsub, file and aws-sqs, not credentials or data-store URLs.

Delivery and data stores

  • Each failed delivery attempt that will be retried now logs a WARN with the destination, the cause’s code and message, the attempt number and next_attempt_at. Before, a retried attempt logged nothing, so a callback that arrived seconds late gave no cause.
  • A closed in-process hand-off no longer delays delivery by 30 seconds. Outbox rows are inserted due after a short grace for the in-process hand-off. When the hand-off had closed before the commit, its rows waited out that grace. Now exactly those rows are made due at once, if they are still as inserted (never a leased, deferred or poisoned row), and the dispatcher is woken, so the next poll tick delivers them. Delivery stays at-least-once with the same dedup.
  • A coded data-store refusal keeps its code. An edited migration that was already applied refuses the store with SUTRA.RUNTIME.DATASTORE.MIGRATION_CHECKSUM, but the step failed with SUTRA.RUNTIME.UNEXPECTED, so the dead letter’s cause_code and its log line never showed the cause. It now fails with the store’s code and logs at ERROR, naming the store and the script, never the key. Routing is unchanged: a non-idempotent flow is still dead-lettered, an idempotent one requeued.

Fixed in the documentation

  • sutra.outbox.retry.base-delay defaults to PT1S, as the code always had it; the configuration guide said PT5S.
  • The 0.6.18 notes said a dropped delivery’s audit record has an empty instance_id. No instance owns it, so it is NULL: select it with instance_id IS NULL.

Tooling

  • Load steps report resources. tools/sutra-load-test run.sh and relay-bench.sh now report engine CPU and RSS and PostgreSQL CPU, IOPS (pg_stat_io) and WAL volume for each step, from step-metrics.sh, as a table and a .metrics.json. A metric it can’t read prints unavailable, never 0.

Security

  • RUSTSEC-2026-0459 is ignored in cargo audit, time-boxed. It is in libsqlite3-sys 0.30.1, which is in Cargo.lock only because sqlx declares its optional SQLite driver through a weak feature. No crate enables SQLite, so it is compiled into nothing: cargo tree -i libsqlite3-sys -e all --target all is empty, and cargo deny, which resolves the real graph, does not see it. No sqlx release allows the fixed 0.39 yet. The ignore is dropped when one does.

For extension authors

  • sutra_envref_spi::is_whole_reference (whether a value is exactly one whole reference form) and is_explicit_empty_default are new.
  • StoreError::with_code and StoreError::code are new in sutra-executor; a store adapter that keeps a refusal’s code passes it through them.
  • OutboxSignal::hand_off in sutra-channels now returns the ids it could not hand off.
  • sutra-channels gains wait_subscriptions and message_types_can_overlap.