Admin

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

Namespace: Goodmem.Client.Api · Class: AdminApi

Reach this surface as client.Admin on a GoodmemClient. Every network method is asynchronous — it returns a Task<T> (or an IAsyncEnumerable<T> for pagination and streaming) and accepts a CancellationToken; the Async suffix marks the standard .NET Task-based async pattern.

Methods

DrainAsync

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

Declaration

public Task<AdminDrainResponse> DrainAsync(AdminDrainRequest? request = null, CancellationToken ct = default)

HTTP — POST /v1/admin:drain

Parameters

Returns

Task<AdminDrainResponse> — an awaitable that resolves to AdminDrainResponse.

Exceptions

Example

var result = await client.Admin.DrainAsync(new AdminDrainRequest { TimeoutSec = 0 });
Console.WriteLine(result.Quiesced);

TransferInstanceOwnershipAsync

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.

Declaration

public Task<TransferInstanceOwnershipResponse> TransferInstanceOwnershipAsync(TransferOwnershipRequest request, CancellationToken ct = default)

HTTP — POST /v1/admin:transferInstanceOwnership

Parameters

Returns

Task<TransferInstanceOwnershipResponse> — an awaitable that resolves to TransferInstanceOwnershipResponse.

Exceptions

Example

var transferredInstance = await client.Admin.TransferInstanceOwnershipAsync(
    new TransferOwnershipRequest { NewOwnerId = "your-principal-id" }
);

BackgroundJobsPurgeAsync

Deletes terminal background jobs older than a retention cutoff.

Declaration

public Task<AdminPurgeJobsResponse> BackgroundJobsPurgeAsync(AdminPurgeJobsRequest? request = null, CancellationToken ct = default)

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

Parameters

Returns

Task<AdminPurgeJobsResponse> — an awaitable that resolves to AdminPurgeJobsResponse.

Exceptions

Example

var result = await client.Admin.BackgroundJobsPurgeAsync(
    new AdminPurgeJobsRequest { OlderThan = "2000-01-01T00:00:00Z", DryRun = true }
);
Console.WriteLine(result.JobsPurged);

LicenseReloadAsync

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

Declaration

public Task<AdminReloadLicenseResponse> LicenseReloadAsync(CancellationToken ct = default)

HTTP — POST /v1/admin/license:reload

Parameters

Returns

Task<AdminReloadLicenseResponse> — an awaitable that resolves to AdminReloadLicenseResponse.

Exceptions

Example

var result = await client.Admin.LicenseReloadAsync();
Console.WriteLine(result.Status);

RetrieveMemoryLogPoliciesCreateAsync

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

Declaration

public Task<RetrieveMemoryLogPolicy> RetrieveMemoryLogPoliciesCreateAsync(CreateRetrieveMemoryLogPolicyRequest? request = null, CancellationToken ct = default)

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

Parameters

Returns

Task<RetrieveMemoryLogPolicy> — an awaitable that resolves to RetrieveMemoryLogPolicy.

Exceptions

Example

var created = await client.Admin.RetrieveMemoryLogPoliciesCreateAsync(
    new CreateRetrieveMemoryLogPolicyRequest
    {
        DisplayName = "audit-doc-example",
        Condition = new RetrieveMemoryLogPolicyCondition { MatchAll = true },
    }
);
Console.WriteLine(created.PolicyId);

RetrieveMemoryLogPoliciesDeleteAsync

Idempotently tombstones an immutable RetrieveMemory log policy.

Declaration

public Task<RetrieveMemoryLogPolicy> RetrieveMemoryLogPoliciesDeleteAsync(string id, DeleteRetrieveMemoryLogPolicyRequest? request = null, CancellationToken ct = default)

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

Parameters

Returns

Task<RetrieveMemoryLogPolicy> — an awaitable that resolves to RetrieveMemoryLogPolicy.

Exceptions

Example

var tombstoned = await client.Admin.RetrieveMemoryLogPoliciesDeleteAsync(
    "your-policy-id",
    new DeleteRetrieveMemoryLogPolicyRequest { Reason = "doc example cleanup" }
);
Console.WriteLine(tombstoned.PolicyId);

RetrieveMemoryLogPoliciesGetAsync

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

Declaration

public Task<RetrieveMemoryLogPolicy> RetrieveMemoryLogPoliciesGetAsync(string id, AdminRetrieveMemoryLogPoliciesGetOptions? options = null, CancellationToken ct = default)

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

Parameters

Returns

Task<RetrieveMemoryLogPolicy> — an awaitable that resolves to RetrieveMemoryLogPolicy.

Exceptions

Example

var fetched = await client.Admin.RetrieveMemoryLogPoliciesGetAsync("your-policy-id");
Console.WriteLine(fetched.DisplayName);

RetrieveMemoryLogPoliciesListAsync

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).

Declaration

public IAsyncEnumerable<RetrieveMemoryLogPolicy> RetrieveMemoryLogPoliciesListAsync(AdminRetrieveMemoryLogPoliciesListOptions? options = null, CancellationToken ct = default)

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

Parameters

Returns

IAsyncEnumerable<RetrieveMemoryLogPolicy> — an async stream; await foreach yields each RetrieveMemoryLogPolicy across pages / events.

Exceptions

Example

// Auto-paginate every retrieve-memory log policy.
await foreach (var policy in client.Admin.RetrieveMemoryLogPoliciesListAsync())
    Console.WriteLine(policy.DisplayName);

Data Models

Types in the Goodmem.Client.Models namespace. Each row lists the C# property, its type, the JSON wire name, and a description.

AdminPurgeJobsRequest

PurgeableBackgroundJobStatus

Terminal background job statuses eligible for purge requests.

String enum: "BACKGROUND_JOB_SUCCEEDED" · "BACKGROUND_JOB_FAILED" · "BACKGROUND_JOB_CANCELED"

AdminPurgeJobsResponse

AdminDrainRequest

AdminDrainResponse

AdminReloadLicenseResponse

ActiveLicenseMetadata

CreateRetrieveMemoryLogPolicyRequest

REST request for creating an immutable RetrieveMemory log policy.

RetrieveMemoryLogPolicyCondition

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.

RetrieveMemoryLogPolicyConditionClause

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

RetrieveMemoryLogPolicy

REST representation of an immutable RetrieveMemory log policy.

DeleteRetrieveMemoryLogPolicyRequest

Optional REST body for tombstoning a RetrieveMemory log policy.

ListRetrieveMemoryLogPoliciesResponse

REST response containing a page of RetrieveMemory log policies.

TransferInstanceOwnershipResponse

The singleton GoodMem instance after its ownership transfer completes.