MigsLab SDKARX.SDK documentation
Ctrl K

PostgreSQL · Types · Routing, paging cookies and capabilities

ArxPagingCookie

Definition

Namespace
ARX.SDK.Query
Package
ARX.SDK
C#
public static class ArxPagingCookie

Writes and reads the opaque cookies of token paging (PagingCookie), for providers that declare ArxCapability.TokenPaging. A cookie carries the provider's own state (for example DynamoDB's last evaluated key) with a version, the provider's name and a fingerprint of the query it belongs to; with a signing key it is also signed (HMAC-SHA256), so a client can't forge or edit one. A cookie from another provider, another query, another key, or one that was changed is ARX1001 InvalidArgument, and the message never echoes it.

Properties

  • const int MaxLength

    The longest cookie ARX reads, in characters: anything longer is refused before decoding.

  • static byte[] ProcessKey { get; }

    This process's own random key: the key of every service that is given none, so services made per request still read each other's cookies. It changes with every process: another instance, or a restart, needs a shared key.

Methods

  • static string Encode(string providerName, ReadOnlySpan<byte> state, string? query = null, byte[]? signingKey = null)

    A cookie for the next page.

    Parameter Type Description
    providerNamestringThe provider writing it (checked when it is read back).
    stateReadOnlySpan<byte>The provider's position, in its own encoding.
    querystring?= nullA description of the query the cookie belongs to (its source, filter and order, never the page): a cookie used with another query is refused. Null for none.
    signingKeybyte[]?= nullOptional: a key of at least 32 bytes to sign the cookie with. The same key reads it back.
  • static byte[] Decode(string cookie, string providerName, string? query = null, byte[]? signingKey = null)

    The provider's state from a cookie it wrote; ARX1001 when the cookie isn't one.

    Parameter Type Description
    cookiestringThe cookie from PagingCookie.
    providerNamestringThe provider reading it: a cookie written by another is refused.
    querystring?= nullThe same description of the query that Encode was given.
    signingKeybyte[]?= nullThe key it was signed with; null when it wasn't signed. A signed cookie read without the key, or the reverse, is refused.
  • static string Encode(string providerName, ReadOnlySpan<byte> state, string query, byte[] key, ArxPagingCookieProtection protection)

    A cookie for the next page, protected as protection says: Sealed (version 2: encrypted and authenticated, AES-256-GCM, so a client can neither read nor change it), Signed (version 1, HMAC-SHA256: readable, not changeable) or Plain (version 1, unsigned).

    Parameter Type Description
    providerNamestringThe provider writing it (checked when it is read back).
    stateReadOnlySpan<byte>The provider's position, in its own encoding.
    querystringA description of the query the cookie belongs to; a cookie used with another query is refused. Null for none.
    keybyte[]The key (32 bytes or more) for Sealed and Signed; ignored for Plain.
    protectionArxPagingCookieProtectionHow the cookie is protected.
  • static byte[] Decode(string cookie, string providerName, string query, byte[] key, ArxPagingCookieProtection protection)

    The provider's state from a cookie protected as protection says; ARX1001 when it isn't one: a cookie protected otherwise, changed, written by another provider or for another query, or sealed with another key (another instance of the application, or before a restart, without a shared key).

    Parameter Type Description
    cookiestringThe cookie from PagingCookie.
    providerNamestringThe provider reading it.
    querystringThe same description of the query that Encode was given.
    keybyte[]The key it was sealed or signed with; ignored for Plain.
    protectionArxPagingCookieProtectionThe protection the service requires.
  • static byte[] NewKey()

    A new random key for paging cookies: 32 bytes.