CidMap

── CID map ───────────────────────────────────────────────────────────────── The persistent key → CID map (docs/cid-map.md): tenant-scoped entries with TTL, pins and GC rooting, converging by newer-entry-wins. The tenant is inferred from the request's TenantId extension; callers never pass it. This service is the inspection/edit surface (UI + CLI); subsystems (sealed log streams, …) write their entries in-process.

Service builder.CidMap, 5 rpcs.

ListCidMapEntries(ListCidMapEntriesRequest) -> ListCidMapEntriesResponse

Page through entries whose key starts with prefix, in key order.

Request: ListCidMapEntriesRequest

message ListCidMapEntriesRequest {
  optional string prefix = 1;
  optional uint32 limit = 2;
  optional string start_after = 3;
  optional bool include_hidden = 4;
}

Field
`prefix`	Only keys starting with this prefix; empty → everything.
`limit`	Page size; 0 → a server-chosen default.
`start_after`	Return keys strictly after this one (the previous page's last key).
`include_hidden`	Also list expired entries and tombstones (for inspection).

Response: ListCidMapEntriesResponse

message ListCidMapEntriesResponse {
  repeated CidMapEntry entries = 1;
  optional bool truncated = 2;
}

Field
`entries`
`truncated`	More entries remain after the last one returned.

GetCidMapEntry(GetCidMapEntryRequest) -> GetCidMapEntryResponse

Resolve one key — optionally asking the key's cluster owners on a local miss.

Request: GetCidMapEntryRequest

message GetCidMapEntryRequest {
  optional string key = 1;
  optional bool resolve = 2;
}

Field
`key`
`resolve`	On a local miss, also ask the key's cluster owners.

Response: GetCidMapEntryResponse

message GetCidMapEntryResponse {
  oneof _entry {
    CidMapEntry entry = 1;
  }
}

Field
`entry`	Unset when the key does not resolve.

PutCidMapEntry(PutCidMapEntryRequest) -> CidMapEntry

Create or replace one entry.

Request: PutCidMapEntryRequest

message PutCidMapEntryRequest {
  optional string key = 1;
  optional string cid = 2;
  optional uint64 ttl_ms = 3;
  optional bool pinned = 4;
  optional string metadata_json = 5;
}

Field
`key`
`cid`
`ttl_ms`	Entry lifetime from now, in milliseconds; 0 → never expires.
`pinned`
`metadata_json`	Optional metadata as a JSON document; empty → none.

Response: CidMapEntry

message CidMapEntry {
  optional string key = 1;
  optional string cid = 2;
  optional uint64 updated_ms = 3;
  optional uint64 expires_ms = 4;
  optional bool pinned = 5;
  optional bool tombstone = 6;
  optional string metadata_json = 7;
}

Field
`key`
`cid`	The CID this key maps to (a GC root while the entry is live).
`updated_ms`	Unix millis of the write that produced this record (the LWW clock).
`expires_ms`	Unix millis after which the entry is a miss; 0 = never expires.
`pinned`	A pinned entry ignores expiry and refuses deletion until unpinned.
`tombstone`	The record of a delete (only surfaced when listing hidden entries).
`metadata_json`	The entry's free-form metadata, rendered as one JSON document.

DeleteCidMapEntry(DeleteCidMapEntryRequest) -> DeleteCidMapEntryResponse

Delete one entry (tombstoned so the delete replicates). Refused while the entry is pinned.

Request: DeleteCidMapEntryRequest

message DeleteCidMapEntryRequest {
  optional string key = 1;
}

Response: DeleteCidMapEntryResponse

message DeleteCidMapEntryResponse {
  optional bool existed = 1;
}

Field
`existed`	Whether a live mapping existed (the tombstone is written either way).

SetCidMapEntryPin(SetCidMapEntryPinRequest) -> CidMapEntry

Pin (make non-removable and permanently rooted) or unpin one entry.

Request: SetCidMapEntryPinRequest

message SetCidMapEntryPinRequest {
  optional string key = 1;
  optional bool pinned = 2;
}

Response: CidMapEntry

The same message as CidMapEntry.

CidMap

On this page