Namespaces & Groups — Calimero Client Py

Overview

A namespace is a coordination boundary tied to an application. Nodes can join a namespace to share state and contexts across the network. Within a namespace, groups organise members into hierarchical units that can be nested into subgroups.

1

Create a namespace

Pick an installed application and an upgrade policy. Optionally assign a human-readable alias.

2

Invite other nodes

Generate an invitation token. Other nodes use it to join the namespace.

3

Organise into groups

Create groups within the namespace, nest them as subgroups, and manage membership.

Namespace Management

create_namespace(application_id, upgrade_policy?, alias?)

Creates a new namespace for an installed application. upgrade_policy defaults to "lazy-on-access". Accepted values: "automatic", "lazy-on-access", "coordinated".

ns = client.create_namespace(
  "app-id",
  upgrade_policy="lazy-on-access",
  alias="my-namespace"
)

get_namespace(namespace_id)

Returns info about a namespace by its ID.

delete_namespace(namespace_id)

Deletes a namespace. This operation is irreversible.

list_namespaces()

Returns all namespaces this node is a member of.

namespaces = client.list_namespaces()

list_namespaces_for_application(application_id)

Returns all namespaces associated with a specific application.

get_namespace_identity(namespace_id)

Returns the identity (keypair) associated with this node's membership in the namespace.

Invitations

create_namespace_invitation(namespace_id, recursive?, expiration_timestamp?)

Generates an invitation token for others to join this namespace. recursive controls whether the invitation grants access to sub-namespaces. expiration_timestamp is a Unix millisecond timestamp after which the invitation expires.

invite = client.create_namespace_invitation(
  "ns-id",
  recursive=True,
  expiration_timestamp=1800000000000
)

join_namespace(namespace_id, invitation_json)

Joins a namespace using an invitation token received from another node. invitation_json is the raw JSON string from the invitation response.

client.join_namespace(
"ns-id",
invitation_json=json.dumps(invite)
)

subscribe_namespace(namespace_id)

Subscribes this node to a namespace it has already joined, enabling it to receive updates and sync events.

Groups

list_namespace_groups(namespace_id)

Returns all groups within a namespace.

groups = client.list_namespace_groups("ns-id")

create_group_in_namespace(namespace_id, group_alias?)

Creates a new group inside a namespace. An optional group_alias gives it a human-readable name.

group = client.create_group_in_namespace(
"ns-id", group_alias="team-a"
)

nest_group(parent_group_id, child_group_id)

Makes one group a subgroup of another. Groups can be nested to form a hierarchy.

client.nest_group("parent-id", "child-id")

unnest_group(parent_group_id, child_group_id)

Removes a group from being a subgroup of another.

client.unnest_group("parent-id", "child-id")

list_subgroups(group_id)

Returns all direct subgroups of a group.

subs = client.list_subgroups("group-id")

Upgrade Policies

When creating a namespace, the upgrade policy controls how application updates are applied across participating nodes.

"automatic"

Nodes upgrade to a new application version as soon as it is published to the namespace.

"lazy-on-access"

Nodes upgrade on their next access to the context after a new version is available. Default.

"coordinated"

Upgrade happens at a scheduled deadline agreed upon by all nodes.