Admin

Services

AdminService Service

Administrative operations for runtime management of the GoodMem server.

Auth: gRPC metadata authorization: Bearer <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 authorization: Bearer <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 'authorization: Bearer ${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 authorization: Bearer <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 authorization: Bearer <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.

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 authorization: Bearer <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 authorization: Bearer <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 authorization: Bearer <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 authorization: Bearer <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.

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.

Admin

On this page