Couchbase Go SDK

The FIT GRPC uses a specific package naming convention to ensure compatibility with Go and Java, and to support hierarchical levels (Cluster, Scope, Collection).

Naming Conventions:

• Flat Directory Structure: Used to allow performers to pull in all protobuf files easily.
• Filename Mapping: Filenames include the package name to replace a directory structure (e.g., sdk.kv.options.proto belongs to package protocol.sdk.kv).
• Specificity Hierarchy: Package names follow a pattern where the right-most part identifies the broad component, and preceding parts add specificity. Example: sdk.cluster.query.index_manager identifies an IndexManager that is a Query type at the Cluster level.
• Shared Code: The protocol.shared package is reserved for code shared between the SDK and transactions.
• Naming Style: Use sdk.kv.Get rather than sdk.kv.SdkKvGet (Exception: transactions.TransactionResult).

Constraints:

• Avoid Import Cycles: Ensure protobuf imports do not create cycles that prevent Go compilation.
• Filename/Message Uniqueness: Do not name a .proto file the same as an existing enum or message (e.g., if PerformerCaps exists, do not name the file performer_caps.proto) to avoid Java compilation errors.

A RangeScan allows you to scan a specific range of keys using ScanTerm boundaries.

ScanTerm

A ScanTerm defines a boundary in the scan.

• Term: The string value of the boundary.
• Exclusive: If true, the boundary value itself is excluded from the scan results.

Helper Functions

• ScanTermMinimum(): Returns a ScanTerm with the value "\x00" (the lowest possible value).
• ScanTermMaximum(): Returns a ScanTerm with the value of utf8.MaxRune (the highest possible value).

Creating a Prefix Scan

You can use NewRangeScanForPrefix(prefix string) to quickly create a RangeScan that starts at the given prefix and ends at the prefix plus the maximum possible value.

// Create a range scan from 'user_' to 'user_z'
rangeScan := gocb.NewRangeScanForPrefix("user_")

// Or manually define terms
manualScan := gocb.RangeScan{
    From: &gocb.ScanTerm{Term: "a", Exclusive: false},
    To:   &gocb.ScanTerm{Term: "z", Exclusive: true},
}

// Execute the scan
result, err := collection.Scan(rangeScan, nil)

The client uses an psOpManager (implemented via psOpManagerDefault) to manage the lifecycle of individual operations. This manager handles several critical concerns for every request:

• Tracing: It creates and manages OpenTelemetry spans to provide observability into request latency and success rates.
• Retries: It tracks retry attempts and uses a RetryStrategy to determine if an operation should be retried based on the error encountered (e.g., ErrServiceNotAvailable).
• Timeouts: It enforces operation-specific timeouts, ensuring requests do not hang indefinitely.
• Idempotency: It tracks whether an operation is idempotent, which is a key factor in deciding if a retry is safe.
• Context: It manages the context.Context associated with the operation.

When an operation is executed, the client uses helper functions like wrapPSOp to wrap the underlying gRPC call with this management logic, automatically handling span creation, timeout enforcement, and retry loops.

The ConfigStreaming message controls how the performer streams results back to the driver. The driver maintains a 10-second buffer to handle out-of-order responses and batching flexibility; the performer should not send data older than this buffer.

Key configuration options include:

• batch_size: An optional hint for the performer to aim for a specific number of results per BatchedResults batch. The performer may return fewer elements than specified to avoid unnecessary waiting.
• flow_control: A boolean to enable flow control. When enabled, the performer should only send responses when the GRPC response stream reports itself as ready. This helps the performer manage its own internal queues and metrics if it cannot keep up with the flow rate.
• enable_metrics: A boolean to determine whether the performer should stream back metrics.

message ConfigStreaming {
  // If present, the performer should stream back BatchedResults, aiming to contain this number of results.
  optional int32 batch_size = 1;

  // Whether the performer should enable flow control.
  bool flow_control = 2;

  // Whether the performer should stream back metrics.
  bool enable_metrics = 3;
}