durablestream

type Client struct {
	// contains filtered or unexported fields
}

type ClientConfig struct {
	// HTTPClient is the underlying HTTP client.
	// Default: http.DefaultClient.
	HTTPClient *http.Client

	// Headers provides headers to include in all requests.
	// Called per-request to allow dynamic values (e.g., auth tokens).
	// This is the primary customization point for authentication.
	Headers HeaderProvider

	// Timeout is the default timeout for all operations (Create, Head, Delete, etc).
	// Zero or negative values default to 30s.
	Timeout time.Duration

	// ReadMode specifies how live reads are handled after catch-up (Section 5.6-5.7).
	// Zero value defaults to ReadModeAuto (catch-up then long-poll).
	ReadMode ReadMode
}

type CreateOptions struct {
	// ContentType sets the content type for the stream.
	// Default: "application/octet-stream"
	ContentType string

	// TTL sets a relative time-to-live for the stream.
	// Zero means no TTL. Mutually exclusive with ExpiresAt.
	TTL time.Duration

	// ExpiresAt sets an absolute expiry time for the stream.
	// Zero means no expiry. Mutually exclusive with TTL.
	ExpiresAt time.Time

	// InitialData sets the initial stream data.
	InitialData []byte
}

type Handler struct {
	// contains filtered or unexported fields
}

type HandlerConfig struct {
	// PathExtractor extracts the stream ID from the request.
	// Default: uses r.URL.Path.
	PathExtractor func(*http.Request) string

	// LongPollTimeout is the maximum wait time for long-poll requests. Default: 30s.
	LongPollTimeout time.Duration

	// SSECloseAfter is the duration after which SSE connections are closed. Default: 60s.
	SSECloseAfter time.Duration

	// MaxAppendSize is the maximum allowed size for append operations. Default: 10MB.
	MaxAppendSize int64

	// ChunkSize is the maximum response size (in bytes) for read operations.
	// When a read would return more data than this limit, results are paginated.
	// Default: 1MB.
	ChunkSize int
}

type HeaderProvider = transport.HeaderProvider

type Message struct {
	// contains filtered or unexported fields
}

type Offset string

type ReadMode = transport.ReadMode

type ReadResult struct {
	Messages   []StoredMessage // Individual messages in offset order
	NextOffset Offset          // Offset to use for next read
	TailOffset Offset          // Current tail (for up-to-date detection)
}

type Reader struct {
	// contains filtered or unexported fields
}

type SendOptions struct {
	// Seq is an optional monotonic sequence number for writer coordination.
	// If provided and less than or equal to the last sequence, returns ErrConflict.
	Seq string
}

type Storage interface {
	// Create creates a new stream. Returns (true, nil) if newly created.
	// Returns (false, nil) if stream exists with matching config (idempotent).
	// Returns (false, error) if stream exists with different config.
	Create(ctx context.Context, streamID string, cfg StreamConfig) (created bool, err error)

	// Append writes data to a stream. Returns the new tail offset.
	// seq is optional sequence number for coordination (Section 5.2).
	//
	// The data slice is only valid for the duration of the call; the caller
	// may reuse or modify it after Append returns. Implementations that need
	// to retain the data (e.g., in-memory storage) must copy it.
	Append(ctx context.Context, streamID string, data []byte, seq string) (Offset, error)

	// Read returns messages from offset. limit is max total bytes to return.
	// Returns messages and the next offset to read from (Section 5.5).
	Read(ctx context.Context, streamID string, offset Offset, limit int) (*ReadResult, error)

	// Head returns stream metadata without reading data (Section 5.4).
	// Returns ErrNotFound if stream doesn't exist (use for existence checks).
	Head(ctx context.Context, streamID string) (*StreamInfo, error)

	// Delete removes a stream (Section 5.3).
	Delete(ctx context.Context, streamID string) error

	// WaitForData blocks until data is available at offset, then returns it.
	// Returns immediately if data already exists at offset.
	// Returns ctx.Err() on timeout/cancellation.
	// Returns ErrNotFound if stream doesn't exist or is deleted while waiting.
	WaitForData(ctx context.Context, streamID string, offset Offset, limit int) (*ReadResult, error)

	// Close releases resources. Safe to call multiple times.
	Close() error
}

type StoredMessage struct {
	Data   []byte // Raw bytes of this message
	Offset Offset // Offset after this message
}

type StreamConfig struct {
	ContentType string
	TTL         time.Duration // Zero means no TTL
	ExpiresAt   time.Time     // Zero means no expiry
	IsPrivate   bool          // If true, use Cache-Control: private (Section 8.1)
}

type StreamData struct {
	Data       []byte // Raw response bytes (empty on 204 timeout)
	NextOffset Offset // Next offset to read from
	Cursor     string // Opaque cursor for long-poll
	UpToDate   bool   // True if caught up to tail
}

type StreamInfo struct {
	ContentType string
	NextOffset  Offset
	TTL         time.Duration // Zero means no TTL
	ExpiresAt   time.Time     // Zero means no expiry
	IsPrivate   bool          // If true, use Cache-Control: private (Section 8.1)
}

type StreamWriter struct {
	// contains filtered or unexported fields
}

type TransportClientConfig struct {
	// Timeout is the default timeout for all operations.
	// Zero or negative values default to 30s.
	Timeout time.Duration

	// ReadMode specifies how live reads are handled after catch-up.
	// Zero value defaults to ReadModeAuto.
	ReadMode ReadMode
}