Couchbase .NET SDK

The FIT GRPC implementation follows specific packaging conventions to ensure compatibility across different languages (Go, Java, C#) and to avoid import cycles.

Naming Conventions:

• Flat Structure: Use a flat directory structure. To distinguish packages, include the package name in the filename (e.g., sdk.kv.options.proto belongs to package protocol.sdk.kv).
• Package Hierarchy: Use a right-to-left specificity model. The right-most part identifies the broad component, and preceding parts add specificity.
  • Example: sdk.cluster.query.index_manager identifies an index_manager that is a query type at the cluster level.
• Shared Code: Use the protocol.shared package for code shared between the SDK and transactions.
• Standard Naming: Use sdk.kv.Get instead of sdk.kv.SdkKvGet. (Exception: transactions.TransactionResult remains as-is for backward compatibility).

Package Mapping Example: To maintain a one-to-one mapping between GRPC packages and generated language packages, use options within the .proto file:

package protocol.sdk.kv;
option csharp_namespace = "Couchbase.Grpc.Protocol.Sdk.Kv";
option java_package = "com.couchbase.client.performer.protocol.sdk.kv";

Performers in the FIT (Functional Integration Testing) framework are designed to be 'dumb-as-rocks passthrough agents'. They should not interpret or manipulate data, but rather act as a transparent bridge between the test environment and the SDK.

Key Implementation Rules:

1. Direct Field Passing: Pass all fields to the SDK exactly as received. Do not modify or prepend values (e.g., do not prepend couchbase:// to connection strings) as this can mask SDK bugs or cause driver issues.
2. Error Handling: If a performer receives an RPC or parameter that it or the SDK cannot recognize or handle, raise UNSUPPORTED. This includes the default behavior for any oneof handling.
3. Handling Optional Fields: Many configuration fields are optional. If a configuration block is not provided, the performer should call the appropriate no-option overload in the SDK (e.g., use cluster.query(statement) instead of cluster.query(statement, options)).

To use the code generation tool, follow these steps:

1. Clone the repositories into an adjacent directory structure:

   mkdir repos
   cd repos
   git clone git@github.com:couchbase/couchbase-net-client.git
   git clone git@github.com:couchbase/protostellar.git

2. Enable the project build: The Couchbase.Stellar.CodeGen project build is disabled by default in the solution build configuration. You must enable it for code generation to occur during a solution build.
3. Execute the build: You can either enable the project in the solution or run dotnet build directly within the Couchbase.Stellar.CodeGen folder.
4. Locate generated files: After building, the stubs and proxies will be located in the obj/Debug/net6.0 directory within Couchbase.Stellar.CodeGen.
5. Update the Stellar project: Copy the generated files into the CodeGen directory of the Couchbase.Stellar project. These files are committed to the repository and should only be updated when the protos change.

$ mkdir repos
$ cd repos
$ git clone git@github.com:couchbase/couchbase-net-client.git
$ git clone git@github.com:couchbase/protostellar.git

# Alternatively, run build directly in the folder
$ dotnet build

Integration tests in Couchbase.IntegrationTests run against a real Couchbase Server. Requirements vary by server version.

For Couchbase Server 4.0+

1. Sample Buckets: Install beer-sample and travel-sample via the Couchbase Console (Settings -> Sample Buckets).
2. Required Buckets:
   • default: No password.
   • authenticated: Password set to secret.
   • memcached: No password.
3. SSL: Install the SSL certificate copied from the Couchbase Console (Security -> Root Certificate).
4. Indexing:
   • Create a default primary index on default, authenticated, beer-sample, and travel-sample (e.g., CREATE PRIMARY INDEX ON default`;).
   • Add an FTS index to the travel-sample bucket named idx-travel.
5. Configuration:
   • Update config.json: Set the Couchbase Server IP hostname and set enhancedAuth to false.
   • Update app.config: Set the hostname and the basic Couchbase client section with the Couchbase Server IP.

For Couchbase Server 5.0+\nIn addition to the 4.0+ steps, perform the following:

1. Ephemeral Bucket: Create an ephemeral bucket.
2. Authentication: Update config.json to set enhancedAuth to true.
3. RBAC User: Create a user named authenticated with the password secret (Note: 5.0+ uses Role-Based Access Control).