Struct ContinuationToken

Namespace

DynaSharp

Assembly

DynaSharp.dll

A position in a Query or Scan, for paging across requests: take Next, hand ToString() to the client, and on the next request pass Parse(string?) of what came back to PageAsync. The text is safe in a URL. It is encoded, not encrypted, and signed only by a client with TokenSigner: without one, a client can read it and choose its position in the partition. The default value is the start of the read.

public readonly struct ContinuationToken : IEquatable<ContinuationToken>

Implements

IEquatable<ContinuationToken>

Inherited Members

object.GetType()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Remarks

Treat the text as opaque, but not as secret: it carries the key values of the last item that was read, as LastEvaluatedKey does in every SDK, signed or not. Encrypt the token if the keys of the table hold what a client must not see. Sign it, with TokenSigner, if the position of a read must not be up to the client. Inside the key condition a position a client picks is only a place among items it may read anyway, and a filter applies from any position, so signing matters where a key condition is all that keeps clients apart from each other's items in a partition they share.

A signed token is a format of its own, version 2: the version, the key and an HMAC-SHA256 of 32 bytes. Parse(string?) takes both formats and checks the shape only, because it has no keys. PageAsync on a client that signs checks the signature, and rejects a plain token that came as text; on a client that does not sign, it rejects a signed one. Both fail with a FormatException, before a request goes out. See ContinuationTokenSigner for what the signature binds.

A token belongs to the query it came from: the same table or index and the same key condition. DynamoDB rejects a key that does not fit with a ValidationException. A token does not expire, and the item of its key need not exist any more: a read continues from the position of the key.

The first byte behind the text is the version of its format, for page and fan-out tokens alike. A token of a format this release does not know, older or newer, fails in Parse(string?) with a FormatException that says so, and the client starts its read again. A patch release reads and writes the formats of the release before it; one that changes a format says so in its notes, so in a rolling deployment across it a client whose request reaches the other release starts its read again. Nothing guesses, because a key read the wrong way would be a wrong position with no error. A token has no limit on its length: one of a page is as long as a key of the table, and one of a fan-out grows with its partitions.

A token of a fan-out query holds two keys per partition, where it continues and what comes next, or the fact that the partition is done, so it is as long as the list of partitions. It holds the direction of the read as well. It goes through Parse(string?) like any other. PageAsync of the fan-out then checks it against the number of its partitions, its direction and the keys of the read, with a FormatException as from Parse(string?), and DynamoDB checks the start keys.

Two tokens are equal if their text is. ToKey() and FromKey(IReadOnlyDictionary<string, AttributeValue>) are the bridge to ExclusiveStartKey and LastEvaluatedKey of the request API.

Properties

HasValue

Gets a value indicating whether this token holds a position. The default value does not: it stands for the start of a read, and for the end in Next.

public bool HasValue { get; }

Property Value

bool

Methods

Equals(ContinuationToken)

Tells whether two tokens are the same position: whether their text is the same, wherever they came from.

public bool Equals(ContinuationToken other)

Parameters

other ContinuationToken

The other token.

Returns

bool

true if the text of both is the same.

Equals(object)

public override bool Equals(object obj)

Parameters

obj object

Returns

bool

FromKey(IReadOnlyDictionary<string, AttributeValue>)

Creates a token from a key of the request API, which continues in a command what a request started: ContinuationToken.FromKey(response.LastEvaluatedKey!). An Item works as well. The attributes are copied.

public static ContinuationToken FromKey(IReadOnlyDictionary<string, AttributeValue> key)

Parameters

key IReadOnlyDictionary<string, AttributeValue>

The key, as LastEvaluatedKey holds it.

Returns

ContinuationToken

The token.

Exceptions

ArgumentNullException

key is null. A missing LastEvaluatedKey means the end of the read, so there is no position to continue from.

ArgumentException

key has no attributes.

GetHashCode()

public override int GetHashCode()

Returns

int

Parse(string?)

Reads a token from its text. null and an empty string are the default value, which is the start of a read, so the first request of a client, which has no token, needs no check, and ToString() always round-trips.

public static ContinuationToken Parse(string? text)

Parameters

text string

What ToString() returned, or nothing.

Returns

ContinuationToken

The token.

Exceptions

FormatException

text is not the text of a token, or of a token of a format this version of the library does not read. The message does not quote it, because it comes from a client.

ToKey()

Creates the key of the request API from this token, which continues in a request what a command started: ExclusiveStartKey = token.ToKey().

public Item? ToKey()

Returns

Item

The key, a new item, or null for the default value, which is no position.

ToString()

Gets the text of the token, to hand to a client.

public override string ToString()

Returns

string

The text, which Parse(string?) reads, or an empty string for the default value.

TryParse(string?, out ContinuationToken)

Reads a token from its text, as Parse(string?) does, so null and an empty string are the default value. Everything a token holds goes into a request, so the text must decode to the version of the format and exactly one key of attribute values; anything else in it is rejected here, whatever a client sends.

public static bool TryParse(string? text, out ContinuationToken token)

Parameters

text string

What ToString() returned, or nothing.

token ContinuationToken

The token, or the default value if the text is not one.

Returns

bool

true if the text is a token or there is none.

Operators

operator ==(ContinuationToken, ContinuationToken)

public static bool operator ==(ContinuationToken left, ContinuationToken right)

Parameters

left ContinuationToken

right ContinuationToken

Returns

bool

operator !=(ContinuationToken, ContinuationToken)

public static bool operator !=(ContinuationToken left, ContinuationToken right)

Parameters

left ContinuationToken

right ContinuationToken

Returns

bool