Admin

gRPC AdminService reference for ReloadLicense, Drain, PurgeBackgroundJobs, GetInstance and other RPCs, with request messages, response types, and service documentation.

Services

AdminService Service

Administrative operations for runtime management of the GoodMem server.

Auth: gRPC metadata x-api-key: <api-key>. Permissions: Each RPC documents its required permission(s). Global Errors: All RPCs may return DEADLINE_EXCEEDED, CANCELLED, UNAVAILABLE, RESOURCE_EXHAUSTED, INTERNAL.

ReloadLicense

Summary: Reloads the active license from the configured license directory.

	Type
Request	`goodmem.v1.ReloadLicenseRequest`
Response	`goodmem.v1.ReloadLicenseResponse`

Auth: gRPC metadata x-api-key: <api-key>. Permissions Required: RELOAD_LICENSE. Request: Empty message. All configuration is server-side. Response: Reports whether a new license was loaded and returns metadata describing the license currently in effect. Side Effects: Updates the in-memory license cache and rate-limit buckets if the license changes. Idempotency: Safe to retry; repeated calls without changing the license file return RELOAD_LICENSE_STATUS_UNCHANGED. Error Codes:

UNAUTHENTICATED: Missing or invalid API key.
PERMISSION_DENIED: Caller lacks RELOAD_LICENSE.
INTERNAL: Unexpected I/O or parsing failure; see message for details. Examples:

grpcurl \
-authority localhost \
-d '{}' \
-H 'x-api-key: ${GOODMEM_API_KEY}' \
localhost:9090 goodmem.v1.AdminService/ReloadLicense

Drain

Summary: Initiates server drain mode, optionally waiting for quiesce.

	Type
Request	`goodmem.v1.DrainRequest`
Response	`goodmem.v1.DrainResponse`

Auth: gRPC metadata x-api-key: <api-key>. Permissions Required: DRAIN_SERVER. Request: Timeout, reason, and an optional wait flag. Response: Reports the lifecycle state after acknowledging the request. Side Effects: Flips readiness to NOT_SERVING, stops background workers, and prevents new mutating RPCs from being accepted. Idempotency: Safe to retry; repeated calls while draining return the current lifecycle state. Error Codes:

UNAUTHENTICATED: Missing or invalid API key.
PERMISSION_DENIED: Caller lacks DRAIN_SERVER.
FAILED_PRECONDITION: Server is still STARTING and cannot drain yet.
DEADLINE_EXCEEDED: wait_for_quiesce requested but the timeout elapsed.

PurgeBackgroundJobs

Summary: Permanently deletes completed background jobs older than a retention threshold.

	Type
Request	`goodmem.v1.PurgeBackgroundJobsRequest`
Response	`goodmem.v1.PurgeBackgroundJobsResponse`

Auth: gRPC metadata x-api-key: <api-key>. Permissions Required: PURGE_BACKGROUND_JOBS. Request: Retention cutoff, optional status filters, dry-run flag, and optional row limit. Response: Counts of job rows and related attempts/references purged (or that would be purged for dry runs). Side Effects: When dry_run is false, removes matching rows from goodmem.bg_job, goodmem.bg_job_attempt, and goodmem.bg_job_reference. Idempotency: Safe to retry; repeated calls will delete any remaining rows that meet the filter. Error Codes:

UNAUTHENTICATED: Missing or invalid API key.
PERMISSION_DENIED: Caller lacks PURGE_BACKGROUND_JOBS.
INVALID_ARGUMENT: Cutoff missing/too recent, statuses invalid, or limit negative.
FAILED_PRECONDITION: Request attempts to purge non-terminal job states.

GetInstance

Reads singleton GoodMem-instance identity and ownership metadata.

	Type
Request	`goodmem.v1.GetInstanceRequest`
Response	`goodmem.v1.GetInstanceResponse`

Auth: gRPC metadata x-api-key: <api-key>.

Authorization Required: Effective READ_INSTANCE on the existing singleton. The built-in ADMIN role supplies this authority; instance ownership alone does not. A scoped authenticating API key must independently retain READ_INSTANCE in its immutable ceiling.

Request: Explicit empty request message.

Response: Stable instance UUID, current human owner UUID, and complete creation and latest ownership-change audit metadata. No credential or other secret material is returned.

Side Effects: None.

Error Codes:

UNAUTHENTICATED: Missing or invalid API key.
PERMISSION_DENIED: Caller lacks effective READ_INSTANCE authority.
FAILED_PRECONDITION: The singleton instance has not been initialized.
INTERNAL: Unexpected authorization or database failure.

Idempotency: Read-only and safe to retry. A concurrent ownership transfer may change a later response.

TransferInstanceOwnership

Summary: Transfers ownership of the singleton GoodMem instance to another human principal.

	Type
Request	`goodmem.v1.TransferInstanceOwnershipRequest`
Response	`goodmem.v1.TransferInstanceOwnershipResponse`

Auth: gRPC metadata x-api-key: <api-key>. Authorization Required: TRANSFER_INSTANCE_OWNERSHIP, derived exclusively from current instance ownership. An ADMIN role, MANAGE_ACCESS, or an ordinary grant is insufficient. A scoped API key must also carry a matching immutable ceiling. Request: UUID of an existing, active human principal who is not already the owner. Response: The updated singleton instance and its ownership audit metadata. Side Effects: Atomically changes the instance owner and moves the synthetic ROOT role mirror to that principal. All ordinary role assignments, including ADMIN, remain unchanged. No credential is created or returned. Idempotency: Not idempotent under response semantics: retrying a completed transfer returns FAILED_PRECONDITION because the requested principal is already owner. After an unknown outcome, read the current owner before retrying. Error Codes:

UNAUTHENTICATED: Missing or invalid API key.
PERMISSION_DENIED: Authenticated principal is not the current instance owner, or a scoped API key lacks the required ceiling.
INVALID_ARGUMENT: new_owner_id is not a valid UUID.
NOT_FOUND: No principal exists with new_owner_id.
FAILED_PRECONDITION: New owner is deleted, is not human, or already owns the instance.
ABORTED: A concurrent ownership or policy change invalidated the transaction; the caller may retry after reading the current owner.

CreateRetrieveMemoryLogPolicy

Summary: Creates an immutable policy that can automatically enable durable RetrieveMemory request logging.

	Type
Request	`goodmem.v1.CreateRetrieveMemoryLogPolicyRequest`
Response	`goodmem.v1.CreateRetrieveMemoryLogPolicyResponse`

Auth: gRPC metadata x-api-key: <api-key>. Permissions Required: CREATE_RETRIEVE_MEMORY_LOG_POLICY. Side Effects: Inserts a policy row and notifies policy-cache listeners after commit. The RPC does not wait for local cache reload. Idempotency: Not idempotent unless the caller supplies a stable policy_id and handles ALREADY_EXISTS. Error Codes:

UNAUTHENTICATED: Missing or invalid API key.
PERMISSION_DENIED: Caller lacks CREATE_RETRIEVE_MEMORY_LOG_POLICY.
INVALID_ARGUMENT: Invalid UUID, label, active window, or condition shape.
NOT_FOUND: A referenced user, API key, or space does not exist.
ALREADY_EXISTS: A policy already exists with the supplied policy_id.

GetRetrieveMemoryLogPolicy

Summary: Retrieves one RetrieveMemory auto-logging policy by ID.

	Type
Request	`goodmem.v1.GetRetrieveMemoryLogPolicyRequest`
Response	`goodmem.v1.GetRetrieveMemoryLogPolicyResponse`

Auth: gRPC metadata x-api-key: <api-key>. Permissions Required: READ_RETRIEVE_MEMORY_LOG_POLICY. Idempotency: Read-only; safe to retry. Error Codes:

UNAUTHENTICATED: Missing or invalid API key.
PERMISSION_DENIED: Caller lacks READ_RETRIEVE_MEMORY_LOG_POLICY.
INVALID_ARGUMENT: policy_id is not a valid UUID.
NOT_FOUND: Policy does not exist, or is deleted and include_deleted is false.

ListRetrieveMemoryLogPolicies

Summary: Lists RetrieveMemory auto-logging policies.

	Type
Request	`goodmem.v1.ListRetrieveMemoryLogPoliciesRequest`
Response	`goodmem.v1.ListRetrieveMemoryLogPoliciesResponse`

Auth: gRPC metadata x-api-key: <api-key>. Permissions Required: LIST_RETRIEVE_MEMORY_LOG_POLICY. Pagination: max_results defaults to 50 and is clamped to [1, 1000]. next_token is opaque and binds to the authenticated requestor and all query-shaping filters. Idempotency: Read-only; safe to retry. Error Codes:

UNAUTHENTICATED: Missing or invalid API key.
PERMISSION_DENIED: Caller lacks LIST_RETRIEVE_MEMORY_LOG_POLICY.
INVALID_ARGUMENT: Invalid filter, sort, or pagination token.

DeleteRetrieveMemoryLogPolicy

Summary: Tombstones one RetrieveMemory auto-logging policy.

	Type
Request	`goodmem.v1.DeleteRetrieveMemoryLogPolicyRequest`
Response	`goodmem.v1.DeleteRetrieveMemoryLogPolicyResponse`

Auth: gRPC metadata x-api-key: <api-key>. Permissions Required: DELETE_RETRIEVE_MEMORY_LOG_POLICY. Side Effects: Marks the policy deleted and notifies policy-cache listeners after commit. The RPC does not wait for local cache reload. Idempotency: Safe to retry for an existing policy; already-tombstoned policies are returned unchanged. Never-existing IDs still return NOT_FOUND. Error Codes:

UNAUTHENTICATED: Missing or invalid API key.
PERMISSION_DENIED: Caller lacks DELETE_RETRIEVE_MEMORY_LOG_POLICY.
INVALID_ARGUMENT: policy_id is not a valid UUID.
NOT_FOUND: Policy does not exist.

Messages

ReloadLicenseRequest

Request payload for ReloadLicense. Empty by design.

LicenseMetadata

Metadata describing the license currently enforced by the server.

Field	Type	Description
`filename`	`string`	Basename of the license file that was parsed (e.g., `license.lic`).
`sha256`	`string`	Hex-encoded SHA-256 digest of the license file contents.
`size_bytes`	`uint64`	Raw size of the license file in bytes.
`modified_at`	`google.protobuf.Timestamp`	Last modified timestamp of the license file, in UTC.

ReloadLicenseResponse

Response payload for ReloadLicense operations.

Field	Type	Description
`status`	`goodmem.v1.ReloadLicenseStatus`	Result of the reload attempt. Always populated.
`message`	`string`	Human-readable description of the outcome. Includes the failure reason when `status` is `RELOAD_LICENSE_STATUS_FAILED`.
`active_license`	`goodmem.v1.LicenseMetadata`	Metadata for the license currently in effect. Present on success and when a previous license remains active after a failure. Absent only when the server has never loaded a license.

DrainRequest

Parameters for initiating a server drain.

Field	Type	Description
`timeout_sec`	`int32`	Maximum seconds to wait for quiesce when `wait_for_quiesce` is true.
`reason`	`string`	Human-readable reason for the drain (e.g., deploy, maintenance).
`wait_for_quiesce`	`bool`	When true, the call blocks until the server reaches QUIESCED or the timeout expires.

DrainResponse

Response returned after acknowledging a drain request.

Field	Type	Description
`state`	`goodmem.v1.LifecycleState`	Lifecycle state after the request was processed.
`quiesced`	`bool`	Whether the server is fully quiesced.
`message`	`string`	Optional status message describing the transition.

PurgeBackgroundJobsRequest

Request payload for purging background jobs.

Field	Type	Description
`older_than`	`google.protobuf.Timestamp`	Only purge jobs that were last updated strictly before this timestamp. Must be at least one hour earlier than the current server time.
`statuses`	`goodmem.v1.BackgroundJobStatus`	Optional filter for job statuses to purge. If empty, defaults to terminal states (`BACKGROUND_JOB_SUCCEEDED`, `BACKGROUND_JOB_FAILED`, `BACKGROUND_JOB_CANCELED`). Non-terminal statuses (`PENDING`, `RUNNING`) are rejected.
`dry_run`	`bool`	When true, only reports counts without deleting any rows.
`limit`	`int32`	Maximum number of job rows to delete in this invocation. Must be >= 0. Zero is treated as "no limit" and purges every eligible row. Negative values are rejected with `INVALID_ARGUMENT`.

PurgeBackgroundJobsResponse

Response payload reporting purge results.

Field	Type	Description
`jobs_purged`	`uint64`	Number of job rows deleted (or that would be deleted for dry runs).
`attempts_purged`	`uint64`	Number of attempt rows deleted (or that would be deleted for dry runs).
`references_purged`	`uint64`	Number of reference rows deleted (or that would be deleted for dry runs).
`dry_run`	`bool`	Echoes whether this was a dry-run invocation.

RetrieveMemoryLogPolicy

Immutable administrative policy that can automatically enable durable logging for matching RetrieveMemory requests.

Field	Type	Description
`policy_id`	`bytes`	Policy UUID (16 bytes).
`display_name`	`string`	Human-readable policy name.
`description`	`string`	Optional free-form description for operators.
`condition`	`...trieveMemoryLogPolicyCondition`	Match condition. Policies are OR'd together globally; clauses inside this policy are OR'd.
`active_from`	`google.protobuf.Timestamp`	Inclusive activation timestamp. Defaults to creation time when omitted on create.
`active_until`	`google.protobuf.Timestamp`	Exclusive deactivation timestamp. Omit for no scheduled end.
`labels`	`...eveMemoryLogPolicy.LabelsEntry`	Operator labels for listing and administration.
`currently_active`	`bool`	Whether the policy is active at the server evaluation time used for the response.
`deleted_at`	`google.protobuf.Timestamp`	Timestamp when the policy was tombstoned. Absent for live policies.
`deleted_by_id`	`bytes`	User UUID (16 bytes) that tombstoned the policy. Absent for live policies.
`delete_reason`	`string`	Optional tombstone reason.
`created_at`	`google.protobuf.Timestamp`	Creation timestamp.
`updated_at`	`google.protobuf.Timestamp`	Last mutation timestamp. For immutable policies, this changes only on tombstone.
`created_by_id`	`bytes`	User UUID (16 bytes) that created the policy.
`updated_by_id`	`bytes`	User UUID (16 bytes) that last updated the policy tombstone fields.

RetrieveMemoryLogPolicy.LabelsEntry

Field	Type	Description
`key`	`string`
`value`	`string`

RetrieveMemoryLogPolicyCondition

Condition attached to one RetrieveMemory log policy.

match_all=true matches every authenticated RetrieveMemory request while active and must not be combined with any_of. Otherwise, at least one any_of clause is required.

Field	Type	Description
`match_all`	`bool`	When true, match every authenticated RetrieveMemory request while the policy is active.
`any_of`	`...MemoryLogPolicyConditionClause`	OR branches for scoped matching. At least one populated clause is required when `match_all` is false.

RetrieveMemoryLogPolicyConditionClause

One OR branch in a RetrieveMemory log policy condition.

Populated dimensions inside one clause are AND'd. Values within a repeated UUID dimension are OR'd. Label selector maps are AND'd by exact key/value pair.

Field	Type	Description
`requestor_user_ids`	`bytes`	Authenticated requestor user UUIDs (16 bytes).
`api_key_ids`	`bytes`	API key UUIDs (16 bytes) used to authenticate the request.
`space_ids`	`bytes`	Post-permission accessible space UUIDs (16 bytes).
`api_key_label_selectors`	`...ause.ApiKeyLabelSelectorsEntry`	Exact API-key label selectors that must all match the authenticating API key.
`space_label_selectors`	`...lause.SpaceLabelSelectorsEntry`	Exact space label selectors that must all match at least one accessible request space.

RetrieveMemoryLogPolicyConditionClause.ApiKeyLabelSelectorsEntry

Field	Type	Description
`key`	`string`
`value`	`string`

RetrieveMemoryLogPolicyConditionClause.SpaceLabelSelectorsEntry

Field	Type	Description
`key`	`string`
`value`	`string`

CreateRetrieveMemoryLogPolicyRequest

Request to create a RetrieveMemory log policy.

Field	Type	Description
`policy_id`	`bytes`	Optional client-provided policy UUID (16 bytes). Server generates one when omitted.
`display_name`	`string`	Human-readable policy name. Required and must be non-blank.
`description`	`string`	Optional free-form description for operators.
`condition`	`...trieveMemoryLogPolicyCondition`	Required match condition.
`active_from`	`google.protobuf.Timestamp`	Inclusive activation timestamp. Defaults to creation time when omitted.
`active_until`	`google.protobuf.Timestamp`	Exclusive deactivation timestamp. Omit for no scheduled end.
`labels`	`...ryLogPolicyRequest.LabelsEntry`	Operator labels for listing and administration.

CreateRetrieveMemoryLogPolicyRequest.LabelsEntry

Field	Type	Description
`key`	`string`
`value`	`string`

CreateRetrieveMemoryLogPolicyResponse

Response returned by CreateRetrieveMemoryLogPolicy.

Field	Type	Description
`policy`	`...mem.v1.RetrieveMemoryLogPolicy`	Created policy.

GetRetrieveMemoryLogPolicyRequest

Request to retrieve a RetrieveMemory log policy by ID.

Field	Type	Description
`policy_id`	`bytes`	Policy UUID (16 bytes).
`include_deleted`	`bool`	Include tombstoned policies instead of returning `NOT_FOUND`.

GetRetrieveMemoryLogPolicyResponse

Response returned by GetRetrieveMemoryLogPolicy.

Field	Type	Description
`policy`	`...mem.v1.RetrieveMemoryLogPolicy`	Requested policy.

ListRetrieveMemoryLogPoliciesRequest

Request to list RetrieveMemory log policies.

Field	Type	Description
`include_deleted`	`bool`	Include tombstoned policies in the result set.
`label_selectors`	`...iesRequest.LabelSelectorsEntry`	Conjunction of exact policy-label filters.
`name_filter`	`string`	Optional case-insensitive substring filter on display name.
`active_at`	`google.protobuf.Timestamp`	Optional active-time filter; returns policies active at this instant.
`max_results`	`int32`	Optional page size. Defaults to 50 and is clamped to [1, 1000].
`next_token`	`string`	Opaque pagination token from a previous response.
`sort_by`	`string`	Sort field: `created_at`, `updated_at`, or `display_name`.
`sort_order`	`goodmem.v1.SortOrder`	Sort direction. Defaults to `DESCENDING` for timestamp sorts and `ASCENDING` for name.

ListRetrieveMemoryLogPoliciesRequest.LabelSelectorsEntry

Field	Type	Description
`key`	`string`
`value`	`string`

ListRetrieveMemoryLogPoliciesResponse

Response returned by ListRetrieveMemoryLogPolicies.

Field	Type	Description
`policies`	`...mem.v1.RetrieveMemoryLogPolicy`	Page of policies.
`next_token`	`string`	Opaque pagination token for the next page, absent on the final page.

ListRetrieveMemoryLogPoliciesNextPageToken

INTERNAL: Pagination token for ListRetrieveMemoryLogPolicies.

Clients MUST treat next_token as opaque and MUST NOT construct or parse it.

Field	Type	Description
`start`	`int32`	Cursor offset position in the result set.
`requestor_id`	`bytes`	Authenticated user ID (16 bytes) for token validation.
`include_deleted`	`bool`	Include-deleted filter from the original request.
`label_selectors`	`...tPageToken.LabelSelectorsEntry`	Label filters from the original request.
`name_filter`	`string`	Name filter from the original request.
`active_at`	`google.protobuf.Timestamp`	Active-at filter from the original request.
`sort_by`	`string`	Sort field from the original request.
`sort_order`	`goodmem.v1.SortOrder`	Sort direction from the original request.

ListRetrieveMemoryLogPoliciesNextPageToken.LabelSelectorsEntry

Field	Type	Description
`key`	`string`
`value`	`string`

DeleteRetrieveMemoryLogPolicyRequest

Request to tombstone a RetrieveMemory log policy.

Field	Type	Description
`policy_id`	`bytes`	Policy UUID (16 bytes).
`reason`	`string`	Optional tombstone reason recorded on first delete.

DeleteRetrieveMemoryLogPolicyResponse

Response returned by DeleteRetrieveMemoryLogPolicy.

Field	Type	Description
`policy`	`...mem.v1.RetrieveMemoryLogPolicy`	Tombstoned policy. Already-deleted policies are returned unchanged.

GoodMemInstance

Singleton GoodMem-instance identity and ownership metadata.

Field	Type	Description
`instance_id`	`bytes`	Stable instance UUID (16 bytes).
`owner_id`	`bytes`	Current human owner principal UUID (16 bytes).
`created_at`	`google.protobuf.Timestamp`	Creation timestamp.
`updated_at`	`google.protobuf.Timestamp`	Timestamp of the most recent ownership change.
`created_by_id`	`bytes`	Principal or API-key actor UUID (16 bytes) that created the instance row.
`updated_by_id`	`bytes`	Principal or API-key actor UUID (16 bytes) that last changed ownership.

GetInstanceRequest

Explicit empty request for reading singleton instance metadata.

GetInstanceResponse

Response returned by GetInstance.

Field	Type	Description
`instance`	`goodmem.v1.GoodMemInstance`	OUTPUT_ONLY; current singleton instance metadata.

TransferInstanceOwnershipRequest

Request to transfer ownership of the singleton GoodMem instance.

Field	Type	Description
`new_owner_id`	`bytes`	Existing, active human principal UUID (16 bytes) that will become instance owner.

TransferInstanceOwnershipResponse

Response returned after transferring ownership of the GoodMem instance.

Field	Type	Description
`instance`	`goodmem.v1.GoodMemInstance`	Updated singleton instance.

Enums

ReloadLicenseStatus

Outcome of a license reload attempt.

Name	Value	Description
`RELOAD_LICENSE_STATUS_UNSPECIFIED`	0	Reserved / invalid status.
`RELOAD_LICENSE_STATUS_LOADED`	1	A new license was parsed and activated successfully.
`RELOAD_LICENSE_STATUS_UNCHANGED`	2	The on-disk license matched the active license; no changes were applied.
`RELOAD_LICENSE_STATUS_FAILED`	3	Reload failed; the previous license remains active (see `message`).
`RELOAD_LICENSE_STATUS_NOT_FOUND`	4	No license file was found in the configured directory.

LifecycleState

Lifecycle states surfaced to administrative clients.

Name	Value	Description
`LIFECYCLE_STATE_UNSPECIFIED`	0	Reserved / invalid state.
`LIFECYCLE_STATE_STARTING`	1	Server is booting and not yet ready.
`LIFECYCLE_STATE_READY`	2	Server is accepting traffic.
`LIFECYCLE_STATE_DRAINING`	3	Server is draining: no new work admitted, in-flight work completing.
`LIFECYCLE_STATE_QUIESCED`	4	Server has drained and is quiesced.

On this page