Reference

IPersistedOperationsService

Package Trax.Api.GraphQL.PersistedOperationsNamespaces Trax.Api.GraphQL.PersistedOperations.Services, Trax.Api.GraphQL.PersistedOperations.GraphQL.ModelsSource IPersistedOperationsService.cs, PersistedOperationsService.cs, IPersistedOperationsManagementGate.cs

The persisted-operation management surface. The persistedOperations GraphQL fields call it, and the dashboard calls it, so an upload, deactivation or restore is accepted or refused the same way, with the same codes, from either.

Registered as a singleton by UsePersistedOperations and by AddPersistedOperationStore.

Signature

public interface IPersistedOperationsService
{
    Task<PersistedOperationsPage> ListAsync(PersistedOperationFilter? filter, int skip, int take, CancellationToken ct);
    Task<PersistedOperationDto?> GetAsync(string id, string? tenantKey, CancellationToken ct);
    Task<IReadOnlyList<PersistedOperationHistoryDto>> GetHistoryAsync(string id, string? tenantKey, int skip, int take, CancellationToken ct);
    Task<UploadPersistedOperationPayload> UploadAsync(UploadPersistedOperationInput input, CancellationToken ct);
    Task<DeactivatePersistedOperationPayload> DeactivateAsync(DeactivatePersistedOperationInput input, CancellationToken ct);
    Task<RestorePersistedOperationPayload> RestoreAsync(RestorePersistedOperationInput input, CancellationToken ct);
}

Members

The inputs, payloads and DTOs are sealed records in Trax.Api.GraphQL.PersistedOperations.GraphQL.Models, the same types the management fields take and return.

TypeFields
UploadPersistedOperationInputId, Document, Description, BypassShapeDiff (default false), Version (default 0), TenantKey
DeactivatePersistedOperationInputId, Reason, TenantKey
RestorePersistedOperationInputId, TenantKey
UploadPersistedOperationPayload, DeactivatePersistedOperationPayload, RestorePersistedOperationPayloadOperation (PersistedOperationDto?), Errors (IReadOnlyList<PersistedOperationError>), Success (true when Operation is set and Errors is empty)
PersistedOperationFilterIsActive, TenantKey, IdStartsWith, all optional
PersistedOperationsPageItems (IReadOnlyList<PersistedOperationDto>), TotalCount
PersistedOperationDtoThe columns of PersistedOperation
PersistedOperationHistoryDtoThe columns of PersistedOperationHistory
PersistedOperationErrorCode, Message, Locations, Path, OldFingerprint, NewFingerprint; see the error payload. PersistedOperationError.NotFound(id) builds the NOT_FOUND error
PersistedOperationErrorLocationLine, Column, 1-based

Behavior

  • The writes never throw for a refused change. The payload carries Success = false and Errors, each with a stable Code: INVALID_INPUT, NOT_FOUND, PARSE_FAILED, SCHEMA_VALIDATION_FAILED or SHAPE_DIFF_VIOLATION. The codes are the ones in the management mutations' error payload.
  • A change that was saved but whose broadcast the broker did not confirm comes back with Success = false, the saved Operation, and one CHANGE_NOT_BROADCAST error. It is in force on this node; other nodes pick it up within the cache's maximum age. Repeating the change sends it again.
  • UploadAsync goes through IPersistedOperationStore.UpsertAsync: schema validation, exactly one operation per document, the shape-diff guardrail, history, cache invalidation and broadcast.
  • DeactivateAsync requires a reason. An unknown id is NOT_FOUND. Deactivating an operation that is already deactivated succeeds, records the new reason, and sends the change to every node again.
  • RestoreAsync acts on any existing operation, active or deactivated.
  • GetAsync returns active and deactivated operations, and null when there is none.
  • ListAsync returns the most recently updated first. GetHistoryAsync returns the most recent change first. For both, take outside 1 to 200 reads as 50 and a negative skip reads as 0.

IPersistedOperationsManagementGate

The management gate the host declared with GateManagement, for a surface that calls the service on a person's behalf without GraphQL. The Trax dashboard asks it before every read and write on its persisted-operations pages, so it refuses the people the persistedOperations fields refuse. Registered by UsePersistedOperations and AddPersistedOperationStore, scoped: resolve it from the caller's scope (the request, or the dashboard's circuit), so a policy whose handler is scoped is evaluated there. The service itself does not ask it: a deploy step or a migration calls the service with no person behind it.

public interface IPersistedOperationsManagementGate
{
    bool IsDeclared { get; }
    Task<bool> AllowsAsync(ClaimsPrincipal user, CancellationToken ct = default);
}
MemberDescription
IsDeclaredTrue once the host declared a gate. When false no surface manages documents
AllowsAsync(user)True when any identity of user is authenticated, satisfies every policy and holds at least one role of each role list. False when no gate is declared, and when a policy is not registered or the host registers no authorization

Example

var service = serviceProvider.GetRequiredService<IPersistedOperationsService>();
 
var result = await service.DeactivateAsync(
    new DeactivatePersistedOperationInput("userProfile_v1", Reason: "replaced by userProfile_v2"),
    cancellationToken
);
 
if (!result.Success)
    throw new InvalidOperationException(string.Join("; ", result.Errors.Select(e => $"{e.Code}: {e.Message}")));

See also