Documentation
¶
Overview ¶
Package sink provides a typed, concurrency-safe Go client for the Sink gRPC service.
Index ¶
- func DeleteResultsError(results []DeleteResult) error
- func ReadResultsError(results []ReadResult) error
- func WriteResultsError(results []WriteResult) error
- type Address
- type BatchError
- type Client
- func (c *Client) CheckHealth(ctx context.Context) error
- func (c *Client) Close() error
- func (c *Client) Delete(ctx context.Context, completionMode CompletionMode, addresses ...Address) ([]DeleteResult, error)
- func (c *Client) Raw() sinkv1.SinkClient
- func (c *Client) Read(ctx context.Context, addresses ...Address) ([]ReadResult, error)
- func (c *Client) Write(ctx context.Context, completionMode CompletionMode, ...) ([]WriteResult, error)
- type ClientOptions
- type CompletionMode
- type Dataset
- func (d *Dataset) Create(ctx context.Context, completionMode CompletionMode, records ...Record) ([]WriteResult, error)
- func (d *Dataset) Merge(ctx context.Context, completionMode CompletionMode, ...) ([]WriteResult, error)
- func (d *Dataset) Read(ctx context.Context, keys ...Key) ([]ReadResult, error)
- func (d *Dataset) Replace(ctx context.Context, completionMode CompletionMode, records ...Record) ([]WriteResult, error)
- func (d *Dataset) Upsert(ctx context.Context, completionMode CompletionMode, records ...Record) ([]WriteResult, error)
- type DatasetOptions
- type DeleteResult
- type DeleteStatus
- type DialOptions
- type Document
- type DocumentEncoding
- type FailureCode
- type Key
- type LuaProgram
- type MergeOptions
- type MissingDocumentMode
- type OperationError
- type ProtocolError
- type ReadResult
- type ReadStatus
- type Record
- type RetryPolicy
- type RevisionToken
- type WriteMode
- type WriteOperation
- type WriteResult
- type WriteStatus
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DeleteResultsError ¶
func DeleteResultsError(results []DeleteResult) error
func ReadResultsError ¶
func ReadResultsError(results []ReadResult) error
func WriteResultsError ¶
func WriteResultsError(results []WriteResult) error
Types ¶
type Address ¶
type Address struct {
// contains filtered or unexported fields
}
Address identifies a record through logical names rather than physical database terminology.
func NewAddress ¶
type BatchError ¶
type BatchError struct {
Failures []*OperationError
}
BatchError collects per-operation failures while preserving errors.Is and errors.As traversal through every failure.
func (*BatchError) Error ¶
func (e *BatchError) Error() string
func (*BatchError) Unwrap ¶
func (e *BatchError) Unwrap() []error
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is safe for concurrent use.
func Dial ¶
func Dial(target string, opts DialOptions) (*Client, error)
Dial creates a lazily connected gRPC client. Call CheckHealth when startup must prove the endpoint is reachable before processing work.
func New ¶
func New(connection grpc.ClientConnInterface, opts ClientOptions) (*Client, error)
New wraps an existing connection without taking ownership of it.
func (*Client) CheckHealth ¶
CheckHealth verifies that the server's standard gRPC health service reports SERVING.
func (*Client) Close ¶
Close closes connections created by Dial. It is a no-op for clients created with New because the caller owns that connection.
func (*Client) Delete ¶
func (c *Client) Delete( ctx context.Context, completionMode CompletionMode, addresses ...Address, ) ([]DeleteResult, error)
Delete permanently deletes records. Deleting an absent record is successful. Large collections are split automatically, and transport failures are not retried. Earlier batches may have completed when a later batch returns an error.
func (*Client) Raw ¶
func (c *Client) Raw() sinkv1.SinkClient
Raw returns the generated gRPC client for advanced or forward-compatible usage.
func (*Client) Read ¶
Read returns results in request order and automatically splits large collections into configured operation-count batches. Transport-level Unavailable errors and retryable per-operation failures are retried because reads are idempotent. Returned operation indexes refer to the original collection.
func (*Client) Write ¶
func (c *Client) Write( ctx context.Context, completionMode CompletionMode, operations ...WriteOperation, ) ([]WriteResult, error)
Write submits mixed put and merge operations and automatically splits large collections into configured operation-count batches. It deliberately does not retry transport failures because the server may already have applied or durably accepted the mutation. Earlier batches may have completed when a later batch returns an error.
type ClientOptions ¶
type ClientOptions struct {
MaxOperations int
ReadRetry RetryPolicy
MaxReceiveMessageBytes int
MaxSendMessageBytes int
}
ClientOptions controls request limits and safe read retries.
type CompletionMode ¶
type CompletionMode = sinkv1.CompletionMode
const ( CompletionWaitUntilApplied CompletionMode = sinkv1.CompletionMode_COMPLETION_MODE_WAIT_UNTIL_APPLIED CompletionReturnAfterAccepted CompletionMode = sinkv1.CompletionMode_COMPLETION_MODE_RETURN_AFTER_ACCEPTED CompletionWaitUntilVisible CompletionMode = sinkv1.CompletionMode_COMPLETION_MODE_WAIT_UNTIL_VISIBLE )
type Dataset ¶ added in v0.4.0
type Dataset struct {
// contains filtered or unexported fields
}
Dataset provides validated, batch-native reads and mutations for one routing and encoding scope. Its methods return decoded results and a BatchError when any individual operation fails.
func NewDataset ¶ added in v0.4.0
func NewDataset(client *Client, opts DatasetOptions) (*Dataset, error)
NewDataset binds stable dataset settings to a Client. MergeProgram is optional and is copied when configured.
func (*Dataset) Create ¶ added in v0.4.0
func (d *Dataset) Create( ctx context.Context, completionMode CompletionMode, records ...Record, ) ([]WriteResult, error)
Create writes complete documents only when their keys do not already exist.
func (*Dataset) Merge ¶ added in v0.4.0
func (d *Dataset) Merge( ctx context.Context, completionMode CompletionMode, missingDocumentMode MissingDocumentMode, records ...Record, ) ([]WriteResult, error)
Merge atomically applies the Dataset's bound Lua program to every incoming record. A Dataset without MergeProgram rejects Merge before sending an RPC.
func (*Dataset) Read ¶ added in v0.4.0
Read fetches one or more records by key. It preserves key order, splits large collections automatically, and treats not-found results as successful reads.
func (*Dataset) Replace ¶ added in v0.4.0
func (d *Dataset) Replace( ctx context.Context, completionMode CompletionMode, records ...Record, ) ([]WriteResult, error)
Replace writes complete documents only when their keys already exist.
func (*Dataset) Upsert ¶ added in v0.4.0
func (d *Dataset) Upsert( ctx context.Context, completionMode CompletionMode, records ...Record, ) ([]WriteResult, error)
Upsert writes complete documents whether or not their keys already exist.
type DatasetOptions ¶ added in v0.4.0
type DatasetOptions struct {
Store string
Namespace string
Dataset string
Encoding DocumentEncoding
MergeProgram *LuaProgram
}
DatasetOptions binds the stable routing, encoding, and optional merge program shared by records in one logical dataset. Completion mode remains a per-call choice because callers of the same dataset can require different durability and visibility guarantees.
type DeleteResult ¶
type DeleteResult struct {
OperationIndex int
Status DeleteStatus
Failure *OperationError
}
func (DeleteResult) Err ¶
func (r DeleteResult) Err() error
type DeleteStatus ¶
type DeleteStatus = sinkv1.DeleteStatus
const ( DeleteAccepted DeleteStatus = sinkv1.DeleteStatus_DELETE_STATUS_ACCEPTED DeleteApplied DeleteStatus = sinkv1.DeleteStatus_DELETE_STATUS_APPLIED DeleteFailed DeleteStatus = sinkv1.DeleteStatus_DELETE_STATUS_FAILED )
type DialOptions ¶
type DialOptions struct {
Client ClientOptions
TransportCredentials credentials.TransportCredentials
GRPCOptions []grpc.DialOption
}
DialOptions controls connection creation. TLS with a minimum version of 1.2 is used when TransportCredentials is nil. Use insecure.NewCredentials only for a trusted plaintext development endpoint.
type Document ¶
type Document struct {
// contains filtered or unexported fields
}
Document contains one immutable, explicitly encoded user object.
func NewDocument ¶
func NewDocument(value any, encoding DocumentEncoding) (Document, error)
NewDocument encodes a Go value using exactly the requested format. JSON uses json struct tags and BSON uses bson struct tags.
func NewRawDocument ¶ added in v0.4.0
func NewRawDocument(encoding DocumentEncoding, payload []byte) (Document, error)
NewRawDocument validates and copies an already encoded document payload.
func (Document) Encoding ¶ added in v0.4.0
func (d Document) Encoding() DocumentEncoding
type DocumentEncoding ¶ added in v0.4.0
type DocumentEncoding = sinkv1.DocumentEncoding
const ( DocumentEncodingJSON DocumentEncoding = sinkv1.DocumentEncoding_DOCUMENT_ENCODING_JSON DocumentEncodingBSON DocumentEncoding = sinkv1.DocumentEncoding_DOCUMENT_ENCODING_BSON )
type FailureCode ¶
type FailureCode = sinkv1.FailureCode
const ( FailureInvalidArgument FailureCode = sinkv1.FailureCode_FAILURE_CODE_INVALID_ARGUMENT FailurePreconditionFailed FailureCode = sinkv1.FailureCode_FAILURE_CODE_PRECONDITION_FAILED FailureNotFound FailureCode = sinkv1.FailureCode_FAILURE_CODE_NOT_FOUND FailureConflict FailureCode = sinkv1.FailureCode_FAILURE_CODE_CONFLICT FailureResourceExhausted FailureCode = sinkv1.FailureCode_FAILURE_CODE_RESOURCE_EXHAUSTED FailureDeadlineExceeded FailureCode = sinkv1.FailureCode_FAILURE_CODE_DEADLINE_EXCEEDED FailureInternal FailureCode = sinkv1.FailureCode_FAILURE_CODE_INTERNAL )
type Key ¶
type Key struct {
// contains filtered or unexported fields
}
Key is an immutable logical record key. Use one of the key constructors.
type LuaProgram ¶ added in v0.2.0
type LuaProgram struct {
// contains filtered or unexported fields
}
LuaProgram is an immutable, self-contained merge rule. Sink verifies the digest and caches the compiled program while executing each merge in a fresh VM.
func NewLuaProgram ¶ added in v0.2.0
func NewLuaProgram(source []byte) (LuaProgram, error)
func (LuaProgram) SHA256 ¶ added in v0.2.0
func (p LuaProgram) SHA256() []byte
func (LuaProgram) Source ¶ added in v0.2.0
func (p LuaProgram) Source() []byte
type MergeOptions ¶
type MergeOptions struct {
Incoming Document
Program LuaProgram
MissingDocumentMode MissingDocumentMode
}
MergeOptions describes a Lua-driven read-modify-write operation.
type MissingDocumentMode ¶
type MissingDocumentMode = sinkv1.MissingDocumentMode
const ( MissingDocumentFail MissingDocumentMode = sinkv1.MissingDocumentMode_MISSING_DOCUMENT_MODE_FAIL MissingDocumentCreate MissingDocumentMode = sinkv1.MissingDocumentMode_MISSING_DOCUMENT_MODE_CREATE )
type OperationError ¶
type OperationError struct {
OperationIndex int
Code FailureCode
Message string
Retryable bool
}
OperationError reports a per-record failure without discarding successful results from the same batch.
func (*OperationError) Error ¶
func (e *OperationError) Error() string
type ProtocolError ¶
ProtocolError means the server returned a structurally invalid response.
func (*ProtocolError) Error ¶
func (e *ProtocolError) Error() string
type ReadResult ¶
type ReadResult struct {
OperationIndex int
Status ReadStatus
Document Document
Revision RevisionToken
Failure *OperationError
}
func (ReadResult) Err ¶
func (r ReadResult) Err() error
type ReadStatus ¶
type ReadStatus = sinkv1.ReadStatus
const ( ReadFound ReadStatus = sinkv1.ReadStatus_READ_STATUS_FOUND ReadNotFound ReadStatus = sinkv1.ReadStatus_READ_STATUS_NOT_FOUND ReadFailed ReadStatus = sinkv1.ReadStatus_READ_STATUS_FAILED )
type Record ¶ added in v0.4.0
Record pairs one logical key with the Go value to encode for a Dataset mutation.
type RetryPolicy ¶
type RetryPolicy struct {
MaxAttempts int
InitialBackoff time.Duration
MaxBackoff time.Duration
Multiplier float64
Jitter float64
}
RetryPolicy controls retries for transport-level Unavailable errors and retryable per-operation failures from Read. Mutating RPCs are never retried automatically.
type RevisionToken ¶
type RevisionToken struct {
// contains filtered or unexported fields
}
RevisionToken is an opaque storage revision returned by Sink.
func (RevisionToken) Bytes ¶
func (r RevisionToken) Bytes() []byte
type WriteMode ¶
const ( WriteCreate WriteMode = sinkv1.WriteMode_WRITE_MODE_CREATE WriteReplace WriteMode = sinkv1.WriteMode_WRITE_MODE_REPLACE WriteUpsert WriteMode = sinkv1.WriteMode_WRITE_MODE_UPSERT )
type WriteOperation ¶
type WriteOperation struct {
// contains filtered or unexported fields
}
WriteOperation is either a put or merge operation. Use NewPut or NewMerge.
func NewMerge ¶
func NewMerge(address Address, opts MergeOptions) (WriteOperation, error)
type WriteResult ¶
type WriteResult struct {
OperationIndex int
Status WriteStatus
Revision RevisionToken
Failure *OperationError
}
func (WriteResult) Err ¶
func (r WriteResult) Err() error
type WriteStatus ¶
type WriteStatus = sinkv1.WriteStatus
const ( WriteAccepted WriteStatus = sinkv1.WriteStatus_WRITE_STATUS_ACCEPTED WriteApplied WriteStatus = sinkv1.WriteStatus_WRITE_STATUS_APPLIED WritePreconditionFailed WriteStatus = sinkv1.WriteStatus_WRITE_STATUS_PRECONDITION_FAILED WriteFailed WriteStatus = sinkv1.WriteStatus_WRITE_STATUS_FAILED )