feat: s2-stream-config header support

[infiniteregrets]

Adds stream_config to AppendInput and as a keyword argument on read, read_session, append_session, and producer. It is JSON-encoded and sent as the s2-stream-config header; the server applies it over the basin's default stream configuration only when the append or read auto-creates the stream, and ignores it if the stream already exists. Sessions resend it on every connect. Same shape as the Rust SDK (stream_config), s2-sdk-go#385, and s2-sdk-typescript#358.

config = StreamConfig(retention_policy=3600)

await stream.append(AppendInput(records=[...], stream_config=config))
await stream.read(start=SeqNum(0), stream_config=config)
async with stream.append_session(stream_config=config) as session: ...
async with stream.read_session(start=SeqNum(0), stream_config=config) as session: ...

Server side: s2-streamstore/s2#718, s2-streamstore/s2-cloud#1767.

[greptile-apps]

Greptile Summary

This PR adds stream auto-creation configuration to unary append/read operations, append/read sessions, and producers.

• Serializes StreamConfig using the existing API mapper and sends it through the s2-stream-config header.
• Preserves encryption, content-type, and accept headers when merging request metadata.
• Retains the configuration across streaming-session reconnects.
• Adds documentation examples and focused coverage for unary and session request paths.
• The wire representation is consistent with the corresponding TypeScript and Go SDK implementations.

Confidence Score: 5/5

The PR appears safe to merge; the new configuration is consistently encoded and propagated without breaking existing calling or header behavior.

No actionable failures remain: the wire format matches the shared SDK contract, all public paths propagate the option, and streaming reconnects continue sending it.

Important Files Changed

Filename	Overview
src/s2_sdk/_ops.py	Adds the public stream-config arguments and correctly merges and propagates the new header through unary and session entry points.
src/s2_sdk/_mappers.py	Encodes the existing API-shaped stream configuration as JSON for the request header.
src/s2_sdk/_types.py	Defines the header constant and adds the documented unary-append configuration field to AppendInput.
src/s2_sdk/_append_session.py	Retains the session-level configuration and passes it to every append-session connection attempt.
src/s2_sdk/_s2s/_append_session.py	Adds the configuration header to append streaming requests, including reconnect attempts.
src/s2_sdk/_s2s/_read_session.py	Adds the configuration header to read streaming requests and reuses it across reconnects.
src/s2_sdk/_producer.py	Propagates producer-level configuration into the underlying append session.
tests/test_stream_config_header.py	Covers wire-field mapping, omission when unset, header coexistence, and unary and streaming request paths.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  C[StreamConfig] --> M[stream_config_header]
  M --> H[s2-stream-config JSON header]
  H --> UA[Unary append]
  H --> UR[Unary read]
  H --> AS[Append session / producer]
  H --> RS[Read session]
  AS --> AR[Resend on reconnect]
  RS --> RR[Resend on reconnect]
  UA --> S[Server auto-creates stream]
  UR --> S
  AR --> S
  RR --> S
  S --> A[Apply over basin defaults]

Loading

_{Reviews (1): Last reviewed commit: "feat: `stream_config` on append, read, a..." | Re-trigger Greptile}