Namespaces

Archive Namespace

Archive a namespace: refuse new work for it, stop what its nodes host, then close its storage. Archiving is final and the name is never reused.

Answers at once with the namespace at status archiving, or archived when it already is; the archive finishes on its own and GET /namespaces?name= shows archived once it has. Every fork of the namespace must be archived first (namespace.has_forks), and every node of the namespace must be disconnected (namespace.has_nodes). The default namespace cannot be archived (namespace.protected), nor can a namespace whose fork has not finished (namespace.pending) or failed (namespace.failed), or one upgraded from an earlier release whose existing actors are still being moved into its volume group (namespace.backfill_pending) or that still has actors the move could not move (namespace.backfill_skipped; destroy them first, as described under creating a namespace).

POST https://rivet.example.com/namespaces/{name}/archive

Examples

Authentication

Send your namespace token as a bearer token in the Authorization header. Every control plane request also requires the namespace query parameter. See Authentication.

Path Parameters

Name	Type	Required	Description
`name`	`string`	Yes	The namespace to archive.

Responses

200

The namespace, with status archiving or archived.

Field	Type	Description
`namespace`	`object`	Name of the namespace to operate in.
`namespace.name`	`string`	Namespace name.
`namespace.create_ts`	`integer`	When the namespace was created, in Unix milliseconds.
`namespace.status`	`"creating" \| "forking" \| "live" \| "archiving" \| "archived" \| "failed"`	`creating` while a new namespace’s volume group is created, `forking` while a fork’s group writes run, `live` once the namespace serves, `archiving` while its nodes stop what they host, `archived` once its storage is closed, for good, and `failed` when a fork was refused after its record was written; the name is then retired.
`namespace.forked_from`	`object`	What the namespace was forked from; `null` for a namespace that is not a fork, and while a fork’s number is not yet known.
`namespace.archived_ts`	`integer \| null`	When the namespace was archived, in Unix milliseconds; `null` unless `archived`.
`namespace.skipped`	`object[]`	Legacy: for a namespace upgraded from an earlier release, the actors the move into its volume group could not move, at most 1,000. Each stays reachable by its ID and key until destroyed; destroying it removes it from this list. Empty for every other namespace. Removed with the backfill in 3.1.
`namespace.skipped[].actor_id`	`string`	ID of the actor.
`namespace.skipped[].name`	`string`	Actor name.
`namespace.skipped[].key`	`string \| null`	Actor key in the slash form, or `null` for an actor without one.
`namespace.skipped_count`	`integer`	Legacy: how many actors the move could not move and are not destroyed yet, which can exceed the length of `skipped`. Forks and archives of the namespace are refused while it is above zero. Removed with the backfill in 3.1.

{
  "namespace": {
    "name": "my-namespace",
    "create_ts": 1700000000000,
    "status": "creating",
    "forked_from": null,
    "archived_ts": null,
    "skipped": [],
    "skipped_count": 0
  }
}

401

auth.invalid_token: the request carries no token, or the token is not valid. auth.token_expired: the token has expired.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details on some errors, for example the retry hint of a refusal or the new actor of a pending fork.

{
  "group": "auth",
  "code": "invalid_token",
  "message": "Authentication token is invalid."
}

403

namespace.protected: the default namespace cannot be archived.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details on some errors, for example the retry hint of a refusal or the new actor of a pending fork.

{
  "group": "namespace",
  "code": "protected",
  "message": "The default namespace cannot be archived."
}

404

namespace.not_found: no namespace has this name.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details on some errors, for example the retry hint of a refusal or the new actor of a pending fork.

{
  "group": "namespace",
  "code": "not_found",
  "message": "The namespace does not exist."
}

409

namespace.has_forks: a fork of this namespace is not archived; archive it first. namespace.has_nodes: a node of this namespace is connected; stop its nodes before archiving it. namespace.pending: the namespace’s fork has not finished. namespace.failed: the namespace’s fork failed. namespace.backfill_skipped: the namespace still has actors from an earlier release that its backfill could not move; destroy them first.

Field	Type	Description
`group`	`string`	Error group, for example `actor`.
`code`	`string`	Error code within the group, for example `not_found`.
`message`	`string`	Human-readable error message.
`metadata`	`any`	Extra details on some errors, for example the retry hint of a refusal or the new actor of a pending fork.

{
  "group": "namespace",
  "code": "has_forks",
  "message": "A fork of this namespace is not archived; archive it first."
}