Expose the paging token API from the C/C++ driver

erichmenge commented 1 year ago

Adds support for getting/setting a paging token that can be reused.

Motivation:

Cassandra allows for paginated result querying to support iterating over large request sets. This pagination mechanism is currently an implementation detail internal to the client. For end clients talking to a web service, being able to jump to a particular page is useful for larger result sets, especially with unreliable network conditions, or additional business logic and processing that may happen on the end client.

Modifications:

Adds a function on Rows to retrieve the current paging token.
Adds a function on Statement to set the paging token.
Include tests for above

Note that the current implementation mostly just exposes the C/C++ token, which is unsafe to use from untrusted sources without additional care to verify that the token is used for the exact same query. For this reason, I'm exposing this as an OpaquePagingStateToken to use internally. The internal token is itself available via withUnsafeBytes. This is so that people can implement their own safety mechanism on top of this primitive. The withUnsafeBytes should act as a signal that care must be taken, and documentation read.

In the future, we may want to provide a higher order abstraction like the Java client has, where the paging token is made safe by way of hash verification.

This pull request provides some early value for those that need paging tokens, while allowing for additional enhancement in the future, if desired.