Admin
Admin service API reference
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 lacksRELOAD_LICENSE.INTERNAL: Unexpected I/O or parsing failure; seemessagefor details. Examples:
grpcurl \
-authority localhost \
-d '{}' \
-H 'authorization: Bearer ${GOODMEM_API_KEY}' \
localhost:9090 goodmem.v1.AdminService/ReloadLicenseDrain
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 lacksDRAIN_SERVER.FAILED_PRECONDITION: Server is still STARTING and cannot drain yet.DEADLINE_EXCEEDED:wait_for_quiescerequested 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 lacksPURGE_BACKGROUND_JOBS.INVALID_ARGUMENT: Cutoff missing/too recent, statuses invalid, or limit negative.FAILED_PRECONDITION: Request attempts to purge non-terminal job states.
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. Zero or negative values are treated as "no limit". |
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. |
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. |