Namespaces

Every worker has an effective namespace. A worker uses default when you do not set one. Use a non-default namespace when multiple tenants or projects must use the same worker name or function id on one engine.

Set a worker namespace

The SDK selects the worker namespace in this order:

Priority	Source
1	The explicit `namespace` SDK option
2	The worker process `III_NAMESPACE` environment variable
3	`default`

Use a non-empty string for a namespace. Leave the option out and the SDK reads III_NAMESPACE itself, then falls back to default; an absent option gives the same result as passing process.env.III_NAMESPACE (os.environ.get("III_NAMESPACE"), std::env::var("III_NAMESPACE").ok()). A null, a None, or any other non-string value is invalid and fails in both the SDK and at the engine. In Go, leave out iii.WithNamespace instead: it refuses a blank name, so iii.WithNamespace(os.Getenv("III_NAMESPACE")) fails when the variable is unset.

SDK option

Use the explicit option when application code must select the namespace. The option has priority over III_NAMESPACE.

Node / TypeScript
Python
Rust
Go
Browser

import { registerWorker } from "iii-sdk";

const worker = registerWorker(process.env.III_URL!, {
  workerName: "state",
  namespace: "orders",
});

import os
from iii import InitOptions, register_worker

worker = register_worker(
    os.environ["III_URL"],
    InitOptions(worker_name="state", namespace="orders"),
)

use iii_sdk::{InitOptions, register_worker};

let url = std::env::var("III_URL").expect("III_URL must be set");
let worker = register_worker(
    &url,
    InitOptions {
        namespace: Some("orders".into()),
        ..Default::default()
    },
);

client := iii.RegisterWorker(os.Getenv("III_URL"),
    iii.WithName("state"),
    iii.WithNamespace("orders"),
)

import { registerWorker } from "iii-browser-sdk";

const worker = registerWorker("ws://localhost:49135", {
  workerName: "checkout-tab",
  namespace: "orders",
});

The browser SDK cannot read a process environment. Pass its namespace explicitly or obtain it from trusted runtime configuration.

Call a function in a namespace

Set namespace on the call. The call resolves only in that namespace. Omit the field and the call resolves in the caller’s own namespace, which is where a worker’s neighbours are. A worker with no namespace of its own resolves in default.

CLI
Node / TypeScript
Python
Rust
Go

iii call --namespace orders state::get key=cart

const result = await worker.call({
  function_id: "state::get",
  payload: { key: "cart" },
  namespace: "orders",
});

result = worker.call({
    "function_id": "state::get",
    "payload": {"key": "cart"},
    "namespace": "orders",
})

use iii_sdk::protocol::CallRequest;
use serde_json::json;

let result = worker
    .call(CallRequest::new("state::get", json!({ "key": "cart" })).namespace("orders"))
    .await?;

result, err := client.Call(ctx, iii.CallRequest{
    FunctionID: "state::get",
    Payload:    json.RawMessage(`{"key":"cart"}`),
    Namespace:  "orders",
})
if err != nil {
    log.Fatal(err)
}
log.Printf("cart: %s", result)

A miss returns function_not_found. The error lists other namespaces where the function id exists.

iii call --namespace <NS> calls a function in that namespace. Without the flag it resolves in default: a CLI invocation has no namespace of its own to inherit.

Observe a namespaced function

An observer resolves the function it observes like a call: the namespace you give with the function_id, else the observing worker’s namespace (engine::* and configuration::* resolve to default). The target resolves the same way; name another namespace with the object form of the target (Go: ObserverOptions.TargetNamespace).

worker.observe(
  { function_id: "orders::create", namespace: "shop" },
  { function_id: "audit::record", namespace: "audit" },
);

See Observers.

Inspect namespaces

Every row from engine::functions::list and engine::workers::list contains a namespace field. The list functions return all namespaces. Pass namespace to an info function for strict lookup:

iii call engine::workers::info --json '{"name":"state","namespace":"orders"}'

Without a namespace, engine::functions::info and engine::workers::info first use a default entry. If no default entry exists, they resolve a name that exists in only one namespace. They return an ambiguity when the name exists in multiple namespaces.

Handle a rejected registration

The engine sends registrationrejected when a live worker already owns the same identity in the same namespace.

Code	Effect
`WORKER_NAMESPACE_CONFLICT`	Fatal. The engine closes the new connection. The SDK does not reconnect.
`FUNCTION_NAMESPACE_CONFLICT`	The engine rejects one function. The worker stays connected and serves its other functions.

For a worker-name conflict, change the worker name or namespace. For a function conflict, remove the duplicate function id or move one worker to another namespace.

A connected worker does not confirm that all its functions are registered. SDKs report a function conflict as a warning. Treat the warning as a startup error when the worker requires every function.

For the wire fields and the exact conflict sequence, see RegistrationRejected.

Configure RBAC for a namespace

An iii-worker-manager expose_functions rule without a namespace applies to default only. Add the exact namespace when the rule must expose a namespaced function. See Namespace-scoped function rules.

Getting Started

Using iii

Understanding iii

Creating Workers

Upgrading

Namespaces

Set a worker namespace

SDK option

Call a function in a namespace

Observe a namespaced function

Inspect namespaces

Handle a rejected registration

Configure RBAC for a namespace

​Set a worker namespace

​SDK option

​Call a function in a namespace

​Observe a namespaced function

​Inspect namespaces

​Handle a rejected registration

​Configure RBAC for a namespace

​Related

Set a worker namespace

SDK option

Call a function in a namespace

Observe a namespaced function

Inspect namespaces

Handle a rejected registration

Configure RBAC for a namespace

Related