Upgrading from 0.22.x to 0.23.x

Redeclare RabbitMQ durable subscriber queues, then adopt namespaces on the surfaces your project uses.

0.23 also removes engine-managed project workers and the iii worker / worker::* lifecycle surface. Complete Move workers from config.yaml to Compose before starting an existing project.

0.23.x adds namespaces as a routing dimension. Workers that declare no namespace land in default and behave exactly as before, so most projects upgrade with no code change. The one hard break is durable queue naming on the RabbitMQ adapter. Apply the steps below that touch surfaces your project uses.

Step 1: Redeclare RabbitMQ durable subscriber queues

Durable subscriber queue names are now namespace-qualified, so two subscribers of the same topic and function id in different namespaces get two queues instead of competing for one. After the upgrade, a 0.23 subscriber declares and consumes a new namespace-qualified queue. The RabbitMQ adapter does not rename, consume, or migrate the old queue. The old queue and its durable binding remain in RabbitMQ until you delete the queue. Messages in it remain unread, and the binding can continue to route copies of new events to it.

Version	Subscriber queue	Dead-letter queue
0.22.x	iii.{topic}.{function_id}.queue	iii.{topic}.{function_id}.dlq
0.23.x	iii.{topic}.{function_id}@{ns}.queue	iii.{topic}.{function_id}@{ns}.dlq

{ns} is the subscriber’s namespace, default when it declared none. Any @ or \ inside a topic, function id, or namespace is backslash-escaped before the join.

Drain the old queues before upgrading. Messages left in a pre-0.23 queue are not migrated and no consumer will read them afterwards.

For each affected subscriber:

1. Stop publishing to the topic.
2. Let the existing consumers drain the old queue to empty.
3. Upgrade and restart. The adapter declares the new namespace-qualified queue on the next subscribe.
4. Delete the drained queue and its dead-letter queue from the broker.

Step 2: Preserve queue storage before moving the worker

The queue implementation is no longer supplied by the engine. Before upgrading, stop publishing and let 0.22.x drain active work, then move iii-queue to the standalone queue Compose package. Keep the same file_path or broker settings under its config_override; changing the path creates an empty store and leaves the old jobs behind.

Follow the queue row in Move workers from config.yaml to Compose, including the configuration-id change from iii-queue to queue. Back up the queue data before the first 0.23 start. iii does not rewrite or relocate it automatically.

Step 3: Tune the registration grace period, if needed

A connection gets its namespace from engine::workers::register. A client can send registration messages before this call. The engine holds these messages until the namespace is known, or until the grace period expires and the connection is set to default.

The default grace period is 5000 ms. Raise it if workers on slow links register but land in default unexpectedly:

worker-compose.yaml

engine:
  registration_namespace_grace_ms: 10000
  workers: {}

Set III_NAMESPACE_GRACE_MS in the engine process environment, not in a worker environment. It applies to namespace resolution for all new worker connections and overrides registration_namespace_grace_ms. A directly supervised engine keeps the same field at the top level of config.yaml.

Step 4: Check for engine::* function ids outside default

Most custom workers do not use the engine:: prefix. Check this step because the new rule rejects an existing custom function that uses the prefix outside default.

Every worker has a namespace. A worker uses default if you do not specify a namespace. engine::* is reserved for engine infrastructure, which is registered in default. If a worker in a non-default namespace registers an engine::* function id, the engine rejects that registration with FUNCTION_NAMESPACE_CONFLICT. The connection stays open, and its other functions continue to serve requests. Rename the function with your own service::name prefix.

The standalone queue worker registers its infrastructure functions in default. The rule does not reject those functions. It applies to a custom worker connection that registers an engine::* function in a non-default namespace.

Step 5: Scope RBAC rules when adopting a namespace

Two RBAC surfaces changed, and both matter only for a worker that leaves default.

First, expose_functions rules on the iii-worker-manager RBAC listener are namespace-scoped. A rule that names no namespace applies to default only, so it will not expose a function reached in another namespace. When you move a worker into a namespace, scope its rules to match:

expose_functions:
  - match: "orders::*"
    namespace: orders

Add one rule for each namespace the session reaches. See Namespace-scoped function rules for the matching syntax.

Second, allowed_functions on the auth result now applies in default only. It used to apply in every namespace, so a grant issued for one tenant answered for every other tenant exposing the same function id. If your auth function returns allowed_functions for a worker that runs in a namespace, move those grants into namespaces, which the auth result now carries. See Scope a session to namespaces.

forbidden_functions is unchanged and still applies in every namespace. An auth function that returns no namespaces keeps the behaviour it had.

Migration checklist

• Drain and delete pre-0.23 RabbitMQ subscriber and dead-letter queues (Step 1)
• Stop publishers and drain active iii-queue jobs before the upgrade (Step 2)
• Back up the queue data and preserve its file_path or broker settings (Step 2)
• Rename the queue configuration id from iii-queue to queue (Step 2)
• Raise registration_namespace_grace_ms if workers land in default unexpectedly (Step 3)
• Rename engine::* function ids registered by namespaced workers (Step 4)
• Add namespace: to expose_functions rules for namespaced workers (Step 5)
• Move allowed_functions grants for namespaced workers into namespaces (Step 5)

Result

The project runs on 0.23.x with durable subscriptions consuming from namespace-qualified queues. Workers that declare no namespace keep routing through default exactly as they did on 0.22.x, and workers that declare one own their function ids inside it.

To configure workers and calls, see Use namespaces. To understand strict routing, see Namespaces.