> ## Documentation Index
> Fetch the complete documentation index at: https://iii.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.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.

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

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: Verify migration of engine-managed queues

This step applies when your deployment stores durable queues in the queue storage managed by the
engine. It does not apply to RabbitMQ.

At startup, before queue consumers start, the engine scans the stored durable subscriber queues. For
each queue without a namespace, it moves the waiting, active, delayed, and dead-letter entries to the
same queue in `default`. Active jobs return to the waiting state. Delayed jobs keep their scheduled
time.

| Before                   | After                            |
| ------------------------ | -------------------------------- |
| `{topic}::{function_id}` | `{topic}::{function_id}@default` |

The engine uses `default` because a legacy queue does not contain a namespace. The migration is
idempotent. If startup stops during migration, the next startup continues without duplicating jobs.
The engine logs each migrated queue:

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
Drained legacy subscriber queue into its namespace
```

If a legacy queue name contains `@`, the engine cannot determine if the character is part of the old
name or marks a namespace. It does not migrate that queue and logs this warning:

```text theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
Queue name contains the namespace separator; skipped by the legacy subscriber-queue drain
```

<Warning>
  If you see this warning, stop publishing. Restart 0.22.x with the same queue storage, let its
  consumer drain the skipped queue, and then repeat the upgrade.
</Warning>

## 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:

```yaml config.yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
registration_namespace_grace_ms: 10000
```

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`.

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

<Note>
  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`.
</Note>

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 queue worker supplied with the engine registers its `engine::queue::*` functions in `default`.
The rule does not reject these 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:

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
expose_functions:
  - match: "orders::*"
    namespace: orders
```

Add one rule for each namespace the session reaches. See
[Namespace-scoped function rules](../creating-workers/worker-manager#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](../creating-workers/worker-manager#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)
* [ ] Confirm the engine logged each legacy queue migration on startup (Step 2)
* [ ] Recover each queue that the legacy migration skipped because its name contains `@` (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.

<Note>
  To configure workers and calls, see [Use namespaces](../using-iii/namespaces). To understand strict
  routing, see [Namespaces](../understanding-iii/namespaces).
</Note>