gRPC API

Source repository for the S2 gRPC API is github.com/s2-streamstore/s2-protos

​

AccountService

Operate on an S2 account.

Method Name	Request Type	Response Type	Description	Options
ListBasins	ListBasinsRequest	ListBasinsResponse	List basins.	idempotency_level: NO_SIDE_EFFECTS
CreateBasin	CreateBasinRequest	CreateBasinResponse	Create a new basin. Provide a client request token with the S2-Request-Token header for idempotent retry behaviour.	idempotency_level: IDEMPOTENT
DeleteBasin	DeleteBasinRequest	DeleteBasinResponse	Delete a basin. Basin deletion is asynchronous, and may take a few minutes to complete.	idempotency_level: IDEMPOTENT
ReconfigureBasin	ReconfigureBasinRequest	ReconfigureBasinResponse	Update basin configuration.	idempotency_level: IDEMPOTENT
GetBasinConfig	GetBasinConfigRequest	GetBasinConfigResponse	Get basin configuration.	idempotency_level: NO_SIDE_EFFECTS

​

BasinService

Operate on an S2 basin.

Method Name	Request Type	Response Type	Description	Options
ListStreams	ListStreamsRequest	ListStreamsResponse	List streams.	idempotency_level: NO_SIDE_EFFECTS
CreateStream	CreateStreamRequest	CreateStreamResponse	Create a stream. Provide a client request token with the S2-Request-Token header for idempotent retry behaviour.	idempotency_level: IDEMPOTENT
DeleteStream	DeleteStreamRequest	DeleteStreamResponse	Delete a stream. Stream deletion is asynchronous, and may take a few minutes to complete.	idempotency_level: IDEMPOTENT
GetStreamConfig	GetStreamConfigRequest	GetStreamConfigResponse	Get stream configuration.	idempotency_level: NO_SIDE_EFFECTS
ReconfigureStream	ReconfigureStreamRequest	ReconfigureStreamResponse	Update stream configuration.	idempotency_level: IDEMPOTENT

​

StreamService

Operate on an S2 stream.

Method Name	Request Type	Response Type	Description	Options
CheckTail	CheckTailRequest	CheckTailResponse	Check the sequence number that will be assigned to the next record on a stream.	idempotency_level: NO_SIDE_EFFECTS
Append	AppendRequest	AppendResponse	Append a batch of records to a stream.	None
AppendSession	AppendSessionRequest stream	AppendSessionResponse stream	Append batches of records to a stream continuously, while guaranteeing pipelined requests are processed in order. If any request fails, the session is terminated.	None
Read	ReadRequest	ReadResponse	Retrieve a batch of records from a stream.	idempotency_level: NO_SIDE_EFFECTS
ReadSession	ReadSessionRequest	ReadSessionResponse stream	Retrieve batches of records from a stream continuously.	idempotency_level: NO_SIDE_EFFECTS

​

AppendInput

Input for append requests.

Field	Type	Label	Description
stream	string		Stream name. Optional for subsequent requests in the session.
records	AppendRecord	repeated	Batch of records to append atomically, which must contain at least one record, and no more than 1000. The total size of a batch of records may not exceed 1MiB of metered bytes.
match_seq_num	uint64	optional	Enforce that the sequence number issued to the first record matches.
fencing_token	bytes	optional	Enforce a fencing token which must have been previously set by a fence command record.

​

AppendOutput

Output from append response.

Field	Type	Label	Description
start_seq_num	uint64		Sequence number of first record appended.
end_seq_num	uint64		Sequence number of last record appended + 1. end_seq_num - start_seq_num will be the number of records in the batch.
next_seq_num	uint64		Sequence number of last durable record on the stream + 1. This can be greater than end_seq_num in case of concurrent appends.

​

AppendRecord

Record to be appended to a stream.

Field	Type	Label	Description
headers	Header	repeated	Series of name-value pairs for this record.
body	bytes		Body of this record.

​

AppendRequest

Append request.

Field	Type	Label	Description
input	AppendInput		Request parameters for an append.

​

AppendResponse

Append response.

Field	Type	Label	Description
output	AppendOutput		Response details for an append.

​

AppendSessionRequest

Append session request.

Field	Type	Label	Description
input	AppendInput		Request parameters for an append.

​

AppendSessionResponse

Append session response.

Field	Type	Label	Description
output	AppendOutput		Response details for an append.

​

BasinConfig

Basin configuration.

Field	Type	Label	Description
default_stream_config	StreamConfig		Default stream configuration.

​

BasinInfo

Basin information.

Field	Type	Label	Description
name	string		Basin name.
scope	string		Basin scope.
cell	string		Cell assignment.
state	BasinState		Basin state.

​

CheckTailRequest

Check tail request.

Field	Type	Label	Description
stream	string		Stream name.

​

CheckTailResponse

Check tail response.

Field	Type	Label	Description
next_seq_num	uint64		Sequence number that will be assigned to the next record on the stream.

​

CreateBasinRequest

Create basin request.

Field	Type	Label	Description
basin	string		Basin name, which must be globally unique. It can be omitted to let the service assign a unique name. The name must be between 8 and 48 characters, comprising lowercase letters, numbers and hyphens. It cannot begin or end with a hyphen.
config	BasinConfig		Basin configuration.
scope	string		Basin scope. It should be formatted as ”:”, e.g. “aws:us-east-1”.
cell	string		Explicit cell assignment, if it is owned by the account.

​

CreateBasinResponse

Create basin response.

Field	Type	Label	Description
info	BasinInfo		Information about the newly created basin.

​

CreateStreamRequest

Create stream request.

Field	Type	Label	Description
stream	string		Stream name, which must be unique within the basin. It can be an arbitrary string upto 512 characters. Backslash (/) is recommended as a delimiter for hierarchical naming.
config	StreamConfig		Configuration for the new stream.

​

CreateStreamResponse

Create stream response.

Field	Type	Label	Description
info	StreamInfo		Information about the newly created stream.

​

DeleteBasinRequest

Delete basin request.

Field	Type	Label	Description
basin	string		Name of the basin to delete.

​

DeleteBasinResponse

Delete basin response.

​

DeleteStreamRequest

Delete stream request.

Field	Type	Label	Description
stream	string		Stream name.

​

DeleteStreamResponse

Delete stream response.

​

GetBasinConfigRequest

Get basin configuration request.

Field	Type	Label	Description
basin	string		Basin name.

​

GetBasinConfigResponse

Get basin configuration response.

Field	Type	Label	Description
config	BasinConfig		Basin configuration.

​

GetStreamConfigRequest

Get stream configuration request.

Field	Type	Label	Description
stream	string		Stream name.

​

GetStreamConfigResponse

Get stream configuration response.

Field	Type	Label	Description
config	StreamConfig		Stream configuration.

​

Header

Headers add structured information to a record as name-value pairs.

Header names cannot be empty, with the exception of “command messages” that are interpreted by S2. A command message is signalled by a sole header with empty name. The header value represents an operation, and the record body acts as a payload for the command. S2 client SDKs provide high-level APIs for command messages, and advanced users may also create them directly.

Valid operations are as follows:

• fence with an upto 16 byte payload to set a fencing token. An empty payload clears the token. Fencing is strongly consistent, and subsequent appends that specify a fencing token will be rejected if it does not match.
• trim with exactly 8 big-endian bytes as payload representing the desired earliest sequence number. This sequence number is only allowed to advance, and any regression will be ignored. Trimming is eventually consistent, and trimmed records may be visible for a brief period.

Field	Type	Label	Description
name	bytes		Header name blob.
value	bytes		Header value blob.

​

ListBasinsRequest

List basins request.

Field	Type	Label	Description
prefix	string		List basin names that begin with this prefix.
start_after	string		Only return basins names that lexicographically start after this name. This can be the last basin name seen in a previous listing, to continue from there. It must be greater than or equal to the prefix if specified.
limit	uint64		Number of results, upto a maximum of 1000.

​

ListBasinsResponse

List basins response.

Field	Type	Label	Description
basins	BasinInfo	repeated	Matching basins.
has_more	bool		If set, indicates there are more results that can be listed with start_after.

​

ListStreamsRequest

List streams request.

Field	Type	Label	Description
prefix	string		List stream names that begin with this prefix.
start_after	string		Only return stream names that lexicographically start after this name. This can be the last stream name seen in a previous listing, to continue from there. It must be greater than or equal to the prefix if specified.
limit	uint64		Number of results, upto a maximum of 1000.

​

ListStreamsResponse

List streams response.

Field	Type	Label	Description
streams	StreamInfo	repeated	Matching streams.
has_more	bool		If set, indicates there are more results that can be listed with start_after.

​

ReadLimit

If both count and bytes are non-zero, either limit may be hit.

Field	Type	Label	Description
count	uint64		A value of zero signifies no count limit.
bytes	uint64		A value of zero signifies no bytes limit. Record sizes are calculated as metered bytes.

​

ReadOutput

Output from read response.

Field	Type	Label	Description
batch	SequencedRecordBatch		Batch of records. This batch can be empty only if a ReadLimit was provided in the associated read request, but the first record that could have been returned would violate the limit.
first_seq_num	uint64		Sequence number for the first record on this stream, in case the requested start_seq_num is smaller. If returned in a streaming read session, this will be a terminal reply, to signal that there is uncertainty about whether some records may be omitted. The client can re-establish the session starting at this sequence number.
next_seq_num	uint64		Sequence number for the next record on this stream, in case the requested start_seq_num was larger. If returned in a streaming read session, this will be a terminal reply.

​

ReadRequest

Read request.

Field	Type	Label	Description
stream	string		Stream name.
start_seq_num	uint64		Starting sequence number (inclusive).
limit	ReadLimit	optional	Limit on how many records can be returned upto a maximum of 1000, or 1MiB of metered bytes.

​

ReadResponse

Read response.

Field	Type	Label	Description
output	ReadOutput		Response details for a read.

​

ReadSessionRequest

Read session request.

Field	Type	Label	Description
stream	string		Stream name.
start_seq_num	uint64		Starting sequence number (inclusive).
limit	ReadLimit	optional	Limit on how many records can be returned. When a limit is specified, the session will be terminated as soon as the limit is met, or when the current tail of the stream is reached — whichever occurs first. If no limit is specified, the session will remain open after catching up to the tail, and continue tailing as new messages are written to the stream.

​

ReadSessionResponse

Read session response.

Field	Type	Label	Description
output	ReadOutput		Response details for a read.

​

ReconfigureBasinRequest

Reconfigure basin request.

Field	Type	Label	Description
basin	string		Basin name.
config	BasinConfig		Basin configuration.
mask	google.protobuf.FieldMask		Specifies the pieces of configuration being updated. See https://protobuf.dev/reference/protobuf/google.protobuf/#field-mask

​

ReconfigureBasinResponse

Reconfigure basin response.

Field	Type	Label	Description
config	BasinConfig		Basin configuration.

​

ReconfigureStreamRequest

Reconfigure stream request.

Field	Type	Label	Description
stream	string		Stream name.
config	StreamConfig		Stream configuration with updated values.
mask	google.protobuf.FieldMask		Specifies the pieces of configuration being updated. See https://protobuf.dev/reference/protobuf/google.protobuf/#field-mask

​

ReconfigureStreamResponse

Reconfigure stream response.

Field	Type	Label	Description
config	StreamConfig		Stream configuration.

​

SequencedRecord

Record retrieved from a stream.

Field	Type	Label	Description
seq_num	uint64		Sequence number for this record.
headers	Header	repeated	Series of name-value pairs for this record.
body	bytes		Body of this record.

​

SequencedRecordBatch

A batch of sequenced records.

Field	Type	Label	Description
records	SequencedRecord	repeated	Batch of sequenced records.

​

StreamConfig

Stream configuration.

Field	Type	Label	Description
storage_class	StorageClass		Storage class for recent writes. This is the main cost:performance knob in S2.
age	uint64		Age in seconds for automatic trimming of records older than this threshold. If set to 0, the stream will have infinite retention.

​

StreamInfo

Stream information.

Field	Type	Label	Description
name	string		Stream name.
created_at	uint32		Creation time in seconds since Unix epoch.
deleted_at	uint32	optional	Deletion time in seconds since Unix epoch, if the stream is being deleted.

​

BasinState

Current state of the basin.

Name	Number	Description
BASIN_STATE_UNSPECIFIED	0	Unspecified.
BASIN_STATE_ACTIVE	1	Basin is active.
BASIN_STATE_CREATING	2	Basin is being created.
BASIN_STATE_DELETING	3	Basin is being deleted.

​

StorageClass

Storage class for recent writes.

Name	Number	Description
STORAGE_CLASS_UNSPECIFIED	0	Unspecified, which is currently overridden to STORAGE_CLASS_EXPRESS.
STORAGE_CLASS_STANDARD	1	Standard, which offers end-to-end latencies under 500 ms.
STORAGE_CLASS_EXPRESS	2	Express, which offers end-to-end latencies under 50 ms.