Admin

Go SDK reference for server administration: retrieval log policies, ownership transfer, draining, license reloads, and job purging.

package goodmem // import "fury.io/pairsys/goodmem"

Server lifecycle ops — drain, license reload, background-job purge.

Methods are called as client.Admin().<Method>(ctx, ...) on a *goodmem.Client. Service: AdminService.

Index

type AdminService
type AdminPurgeJobsRequest
type PurgeableBackgroundJobStatus
type AdminPurgeJobsResponse
type AdminDrainRequest
type AdminDrainResponse
type AdminReloadLicenseResponse
type ActiveLicenseMetadata
type CreateRetrieveMemoryLogPolicyRequest
type RetrieveMemoryLogPolicyCondition
type RetrieveMemoryLogPolicyConditionClause
type RetrieveMemoryLogPolicy
type DeleteRetrieveMemoryLogPolicyRequest
type ListRetrieveMemoryLogPoliciesResponse
type TransferInstanceOwnershipResponse

type AdminService

type AdminService struct{ … }

Access this service as client.Admin() on a *goodmem.Client. Its methods follow.

func (s *AdminService) Drain

func (s *AdminService) Drain(ctx context.Context, req *models.AdminDrainRequest) (*models.AdminDrainResponse, error)

Initiates drain mode and optionally waits for the server to quiesce.

HTTP — POST /v1/admin:drain

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
req (*models.AdminDrainRequest) — the request payload. The linked type documents every field and its JSON wire name.

Returns — (*models.AdminDrainResponse, error)

Example

result, err := client.Admin().Drain(ctx, &models.AdminDrainRequest{TimeoutSec: goodmem.Ptr(int32(0))})
if err != nil {
	log.Fatal(err)
}
_ = result.Quiesced

func (s *AdminService) TransferInstanceOwnership

func (s *AdminService) TransferInstanceOwnership(ctx context.Context, req *models.TransferOwnershipRequest) (*models.TransferInstanceOwnershipResponse, error)

Transfers the singleton GoodMem instance to another active human principal. Only the current instance owner may invoke this operation; ADMIN, MANAGE_ACCESS, and ordinary grants are insufficient. Ownership and the synthetic ROOT assignment move atomically. All ordinary roles, including ADMIN, remain unchanged. No credential is created or returned. After an unknown outcome, read the current owner before retrying.

HTTP — POST /v1/admin:transferInstanceOwnership

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
req (*models.TransferOwnershipRequest) — the request payload. The linked type documents every field and its JSON wire name.

Returns — (*models.TransferInstanceOwnershipResponse, error)

Example

transferredInstance, err := client.Admin().TransferInstanceOwnership(
	ctx,
	&models.TransferOwnershipRequest{
		NewOwnerID: "b3303d0a-1a4a-493f-b9bf-38e37153b5a2",
	},
)
if err != nil {
	log.Fatal(err)
}
_ = transferredInstance

func (s *AdminService) BackgroundJobsPurge

func (s *AdminService) BackgroundJobsPurge(ctx context.Context, req *models.AdminPurgeJobsRequest) (*models.AdminPurgeJobsResponse, error)

Deletes terminal background jobs older than a retention cutoff.

HTTP — POST /v1/admin/background-jobs:purge

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
req (*models.AdminPurgeJobsRequest) — the request payload. The linked type documents every field and its JSON wire name.

Returns — (*models.AdminPurgeJobsResponse, error)

Example

result, err := client.Admin().BackgroundJobsPurge(ctx, &models.AdminPurgeJobsRequest{
	OlderThan: goodmem.Ptr("2000-01-01T00:00:00Z"),
	DryRun:    goodmem.Ptr(true),
})
if err != nil {
	log.Fatal(err)
}
_ = result.JobsPurged

func (s *AdminService) LicenseReload

func (s *AdminService) LicenseReload(ctx context.Context) (*models.AdminReloadLicenseResponse, error)

Triggers the server to reload its license file from the configured directory and returns metadata about the currently active license.

HTTP — POST /v1/admin/license:reload

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.

Returns — (*models.AdminReloadLicenseResponse, error)

Example

result, err := client.Admin().LicenseReload(ctx)
if err != nil {
	log.Fatal(err)
}
_ = result.Status

func (s *AdminService) RetrieveMemoryLogPoliciesCreate

func (s *AdminService) RetrieveMemoryLogPoliciesCreate(ctx context.Context, req *models.CreateRetrieveMemoryLogPolicyRequest) (*models.RetrieveMemoryLogPolicy, error)

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

HTTP — POST /v1/admin/retrieve-memory-log-policies

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
req (*models.CreateRetrieveMemoryLogPolicyRequest) — the request payload. The linked type documents every field and its JSON wire name.

Returns — (*models.RetrieveMemoryLogPolicy, error)

Example

created, err := client.Admin().RetrieveMemoryLogPoliciesCreate(ctx, &models.CreateRetrieveMemoryLogPolicyRequest{
	DisplayName: "audit-doc-example",
	Condition:   models.RetrieveMemoryLogPolicyCondition{MatchAll: goodmem.Ptr(true)},
})
if err != nil {
	log.Fatal(err)
}
_ = created.PolicyID

func (s *AdminService) RetrieveMemoryLogPoliciesDelete

func (s *AdminService) RetrieveMemoryLogPoliciesDelete(ctx context.Context, id string, req *models.DeleteRetrieveMemoryLogPolicyRequest) (*models.RetrieveMemoryLogPolicy, error)

Idempotently tombstones an immutable RetrieveMemory log policy.

HTTP — DELETE /v1/admin/retrieve-memory-log-policies/{id}

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
id (string) — The UUID of the policy to delete
req (*models.DeleteRetrieveMemoryLogPolicyRequest) — the request payload. The linked type documents every field and its JSON wire name.

Returns — (*models.RetrieveMemoryLogPolicy, error)

Example

tombstoned, err := client.Admin().RetrieveMemoryLogPoliciesDelete(ctx, "your-policy-id",
	&models.DeleteRetrieveMemoryLogPolicyRequest{Reason: goodmem.Ptr("doc example cleanup")})
if err != nil {
	log.Fatal(err)
}
_ = tombstoned.PolicyID

func (s *AdminService) RetrieveMemoryLogPoliciesGet

func (s *AdminService) RetrieveMemoryLogPoliciesGet(ctx context.Context, id string, params *AdminRetrieveMemoryLogPoliciesGetParams) (*models.RetrieveMemoryLogPolicy, error)

Retrieves a live RetrieveMemory log policy by UUID, or a tombstoned policy when includeDeleted is true.

HTTP — GET /v1/admin/retrieve-memory-log-policies/{id}

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
id (string) — The UUID of the policy to retrieve
params (*AdminRetrieveMemoryLogPoliciesGetParams, optional) — typed query parameters; pass nil for an empty filter set.

Returns — (*models.RetrieveMemoryLogPolicy, error)

Example

fetched, err := client.Admin().RetrieveMemoryLogPoliciesGet(ctx, "your-policy-id", nil)
if err != nil {
	log.Fatal(err)
}
_ = fetched.DisplayName

func (s *AdminService) RetrieveMemoryLogPoliciesList

func (s *AdminService) RetrieveMemoryLogPoliciesList(ctx context.Context, params *AdminRetrieveMemoryLogPoliciesListParams) (*Page[models.RetrieveMemoryLogPolicy], error)

Lists RetrieveMemory log policies with optional tombstone, active-time, name, label, sort, and pagination filters.

LABEL FILTERS: Label filters accept either label.<key>=<value> or label[key]=value (for example, label.environment=production or label[environment]=production).

HTTP — GET /v1/admin/retrieve-memory-log-policies

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
params (*AdminRetrieveMemoryLogPoliciesListParams, optional) — typed query parameters; pass nil for an empty filter set.

Returns — (*Page[models.RetrieveMemoryLogPolicy], error)

Example

// Auto-paginate every retrieve-memory log policy.
page, err := client.Admin().RetrieveMemoryLogPoliciesList(ctx, nil)
if err != nil {
	log.Fatal(err)
}
for policy, err := range page.All(ctx) {
	if err != nil {
		log.Fatal(err)
	}
	_ = policy.DisplayName
}

type AdminPurgeJobsRequest

type AdminPurgeJobsRequest struct{ … }

OlderThan (string, optional, wire olderThan) — ISO-8601 timestamp cutoff; only terminal jobs older than this instant are eligible.
Statuses ([]models.PurgeableBackgroundJobStatus, optional, wire statuses) — Optional terminal background job statuses to target for purging. If omitted, all terminal statuses are eligible. Canonical values are BACKGROUND_JOB_SUCCEEDED, BACKGROUND_JOB_FAILED, and BACKGROUND_JOB_CANCELED. Short aliases SUCCEEDED, FAILED, and CANCELED are also accepted for compatibility.
DryRun (bool, optional, wire dryRun) — If true, report purge counts without deleting any rows.
Limit (int32, optional, wire limit) — Maximum number of jobs to purge in this request. Must be >= 0; 0 means no limit.

type PurgeableBackgroundJobStatus

type PurgeableBackgroundJobStatus string

Terminal background job statuses eligible for purge requests.

String enum (type PurgeableBackgroundJobStatus string): "BACKGROUND_JOB_SUCCEEDED" · "BACKGROUND_JOB_FAILED" · "BACKGROUND_JOB_CANCELED"

type AdminPurgeJobsResponse

type AdminPurgeJobsResponse struct{ … }

JobsPurged (int64, wire jobsPurged) — Number of background job rows removed, or that would be removed during dry-run.
AttemptsPurged (int64, wire attemptsPurged) — Number of background job attempt rows removed.
ReferencesPurged (int64, wire referencesPurged) — Number of background job reference rows removed.
DryRun (bool, wire dryRun) — Whether the purge executed in dry-run mode.

type AdminDrainRequest

type AdminDrainRequest struct{ … }

TimeoutSec (int32, optional, wire timeoutSec) — Maximum seconds to wait for the server to quiesce before returning.
Reason (string, optional, wire reason) — Human-readable reason for initiating drain mode.
WaitForQuiesce (bool, optional, wire waitForQuiesce) — If true, wait for in-flight requests to complete and the server to reach QUIESCED before responding.

type AdminDrainResponse

type AdminDrainResponse struct{ … }

State (string, optional, wire state) — Lifecycle state reported after the drain request was processed.
Quiesced (bool, wire quiesced) — Whether the server has reached the QUIESCED lifecycle state.
Message (string, optional, wire message) — Human-readable status message describing the drain outcome.

type AdminReloadLicenseResponse

type AdminReloadLicenseResponse struct{ … }

Status (string, wire status) — Outcome of the reload attempt, such as LOADED, UNCHANGED, FAILED, or NOT_FOUND.
Message (string, wire message) — Human-readable message describing the reload result.
ActiveLicense (models.ActiveLicenseMetadata, optional, wire activeLicense) — Metadata for the currently active license after reload, or null if no license is active.

type ActiveLicenseMetadata

type ActiveLicenseMetadata struct{ … }

Filename (string, wire filename) — Filename of the active license on disk.
Sha256 (string, wire sha256) — Hex-encoded SHA-256 hash of the active license file.
SizeBytes (int64, wire sizeBytes) — Size of the active license file in bytes.
ModifiedAt (string, wire modifiedAt) — Last modification timestamp of the active license file.

type CreateRetrieveMemoryLogPolicyRequest

type CreateRetrieveMemoryLogPolicyRequest struct{ … }

REST request for creating an immutable RetrieveMemory log policy.

PolicyID (string, optional, wire policyId) — Optional client-provided policy UUID.
DisplayName (string, wire displayName) — Human-readable policy name.
Description (string, optional, wire description) — Optional operator description.
Condition (models.RetrieveMemoryLogPolicyCondition, wire condition) — Policy match condition.
ActiveFrom (int64, optional, wire activeFrom) — Inclusive activation time in milliseconds since epoch.
ActiveUntil (int64, optional, wire activeUntil) — Exclusive deactivation time in milliseconds since epoch.
Labels (map[string]string, optional, wire labels) — Operator labels for listing and administration.

type RetrieveMemoryLogPolicyCondition

type RetrieveMemoryLogPolicyCondition struct{ … }

RetrieveMemory log policy condition. Set matchAll=true to match every authenticated RetrieveMemory request and do not provide anyOf clauses. Otherwise, anyOf is required and must contain at least one non-empty scoped clause.

MatchAll (bool, optional, wire matchAll) — When true, match every authenticated RetrieveMemory request. Must be omitted or false when anyOf contains clauses. Defaults to false when omitted.
AnyOf ([]models.RetrieveMemoryLogPolicyConditionClause, optional, wire anyOf) — OR clauses used for scoped matching. Required and non-empty when matchAll is false or omitted. Must be omitted or empty when matchAll is true. Each clause must include at least one match dimension.

type RetrieveMemoryLogPolicyConditionClause

type RetrieveMemoryLogPolicyConditionClause struct{ … }

One OR clause in a RetrieveMemory log policy condition. All populated dimensions in the clause must match; clauses are ORed together.

RequestorUserIds ([]string, optional, wire requestorUserIds) — Authenticated requestor user UUID strings.
APIKeyIds ([]string, optional, wire apiKeyIds) — API key UUID strings used to authenticate RetrieveMemory requests.
SpaceIds ([]string, optional, wire spaceIds) — Post-permission accessible space UUID strings.
APIKeyLabelSelectors (map[string]string, optional, wire apiKeyLabelSelectors) — Exact API-key label selectors that must all match.
SpaceLabelSelectors (map[string]string, optional, wire spaceLabelSelectors) — Exact space label selectors that must match at least one accessible space.

type RetrieveMemoryLogPolicy

type RetrieveMemoryLogPolicy struct{ … }

REST representation of an immutable RetrieveMemory log policy.

PolicyID (string, wire policyId) — Policy UUID.
DisplayName (string, wire displayName) — Human-readable policy name.
Description (string, optional, wire description) — Optional operator description.
Condition (models.RetrieveMemoryLogPolicyCondition, wire condition) — Policy match condition.
ActiveFrom (int64, wire activeFrom) — Inclusive activation time in milliseconds since epoch.
ActiveUntil (int64, optional, wire activeUntil) — Exclusive deactivation time in milliseconds since epoch.
Labels (map[string]string, wire labels) — Operator labels for listing and administration.
CurrentlyActive (bool, wire currentlyActive) — Whether the policy is active at response evaluation time.
DeletedAt (int64, optional, wire deletedAt) — Tombstone time in milliseconds since epoch.
DeletedByID (string, optional, wire deletedById) — User UUID that tombstoned the policy.
DeleteReason (string, optional, wire deleteReason) — Optional tombstone reason.
CreatedAt (int64, wire createdAt) — Creation time in milliseconds since epoch.
UpdatedAt (int64, wire updatedAt) — Update time in milliseconds since epoch.
CreatedByID (string, wire createdById) — Creator user UUID.
UpdatedByID (string, wire updatedById) — Last-updater user UUID.

type DeleteRetrieveMemoryLogPolicyRequest

type DeleteRetrieveMemoryLogPolicyRequest struct{ … }

Optional REST body for tombstoning a RetrieveMemory log policy.

Reason (string, optional, wire reason) — Optional tombstone reason.

type ListRetrieveMemoryLogPoliciesResponse

type ListRetrieveMemoryLogPoliciesResponse struct{ … }

REST response containing a page of RetrieveMemory log policies.

Policies ([]models.RetrieveMemoryLogPolicy, wire policies) — Policy page.
NextToken (string, optional, wire nextToken) — Opaque token for the next page.

type TransferInstanceOwnershipResponse

type TransferInstanceOwnershipResponse struct{ … }

The singleton GoodMem instance after its ownership transfer completes.

Instance (models.GoodMemInstance, wire instance) — Updated singleton instance and ownership audit metadata.

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

On this page