Schema Registry API #446

w1am · 2025-12-18T12:49:40Z

User description

Extend client module to support schema registry api
Run integration tests against KurrentDB 25.1

PR Type

Enhancement, Tests

Description

Implement comprehensive Schema Registry API client support with 12 core operations for schema and version management
Add schema compatibility checking functionality with detailed error reporting
Generate complete gRPC service definitions and protocol buffer message types for schema registry operations
Implement bidirectional enum mappers and utility functions for gRPC to TypeScript domain type conversions
Add 12 integration test suites covering all schema registry operations (create, read, update, delete, list, lookup, register versions, check compatibility)
Support schema filtering by name prefix, tags, and version IDs with optional schema definition inclusion
Enable schema group management with auto-registration, validation, and compatibility mode settings
Support multiple schema data formats (JSON, Protobuf, Avro, Bytes) and 8 compatibility modes
Export schema registry module to public client API

Diagram Walkthrough

flowchart LR
  proto["Proto Definitions<br/>service, schemas, groups,<br/>validation, shared, errors"]
  generated["Generated Code<br/>gRPC client, message types,<br/>serialization/deserialization"]
  mappers["Mapper Utilities<br/>enum conversion, type mapping,<br/>gRPC to domain conversion"]
  impl["Client Methods<br/>12 schema operations,<br/>compatibility checking"]
  tests["Integration Tests<br/>12 test suites covering<br/>all operations"]
  api["Public API<br/>schemaRegistry module<br/>export"]
  
  proto --> generated
  generated --> mappers
  mappers --> impl
  impl --> api
  impl --> tests

File Walkthrough

Relevant files

Dependencies

17 files

validation_pb.js `Generated protobuf validation message definitions` packages/db-client/generated/kurrentdb/protocols/v2/registry/validation_pb.js Generated protobuf message classes for schema validation including `SchemaCompatibilityError`, `SchemaCompatibilityResult`, `CheckSchemaCompatibilityRequest`, and `CheckSchemaCompatibilityResponse` Implements serialization/deserialization methods for binary protobuf wire format Defines enum `SchemaCompatibilityErrorKind` with 8 error types for schema compatibility validation Provides getter/setter methods for all message fields with proper type conversions	+1789/-0
service_grpc_pb.js `Generated gRPC schema registry service client` packages/db-client/generated/kurrentdb/protocols/v2/registry/service_grpc_pb.js Generated gRPC service client for `SchemaRegistryService` with 24 RPC methods Implements serialization/deserialization functions for all request/response message types Defines service methods for schema groups, schemas, versions, and compatibility checking Exports `SchemaRegistryServiceClient` constructor for client instantiation	+654/-0
shared_pb.js `Generated shared protobuf types and enums` packages/db-client/generated/kurrentdb/protocols/v2/registry/shared_pb.js Generated protobuf definitions for shared types: `ErrorDetails`, `SchemaDataFormat`, and `CompatibilityMode` enums Implements serialization/deserialization for `ErrorDetails` message with `code` and `message` fields Defines 5 schema data formats (JSON, Protobuf, Avro, Bytes, Unspecified) and 8 compatibility modes	+233/-0
service_pb.js `Generated service protocol aggregation file` packages/db-client/generated/kurrentdb/protocols/v2/registry/service_pb.js Generated minimal service definition file that imports and extends proto objects from groups, schemas, and validation modules Serves as aggregation point for all registry service protocol definitions	+29/-0
errors_pb.js `Generated registry error definitions` packages/db-client/generated/kurrentdb/protocols/v2/registry/errors_pb.js Generated protobuf error definitions for registry operations Defines `RegistryError` enum with `REGISTRY_ERROR_UNSPECIFIED` value Imports RPC protocol definitions as dependency	+34/-0
schemas_grpc_pb.js `Generated schemas gRPC placeholder` packages/db-client/generated/kurrentdb/protocols/v2/registry/schemas_grpc_pb.js Generated placeholder file indicating no gRPC services defined in schemas proto	+1/-0
validation_grpc_pb.js `Generated validation gRPC placeholder` packages/db-client/generated/kurrentdb/protocols/v2/registry/validation_grpc_pb.js Generated placeholder file indicating no gRPC services defined in validation proto	+1/-0
errors_grpc_pb.js `Generated errors gRPC placeholder` packages/db-client/generated/kurrentdb/protocols/v2/registry/errors_grpc_pb.js Generated placeholder file indicating no gRPC services defined in errors proto	+1/-0
groups_grpc_pb.js `Generated groups gRPC placeholder` packages/db-client/generated/kurrentdb/protocols/v2/registry/groups_grpc_pb.js Generated placeholder file indicating no gRPC services defined in groups proto	+1/-0
shared_grpc_pb.js `Generated shared gRPC placeholder` packages/db-client/generated/kurrentdb/protocols/v2/registry/shared_grpc_pb.js Generated placeholder file indicating no gRPC services defined in shared proto	+1/-0
service_grpc_pb.d.ts `Schema Registry gRPC Service Type Definitions` packages/db-client/generated/kurrentdb/protocols/v2/registry/service_grpc_pb.d.ts Generated gRPC service definitions for Schema Registry API with 19 RPC methods Defines interfaces for service implementation, server handlers, and client stubs Supports schema group operations (create, update, delete, get, list) Supports schema operations (create, update, delete, get, list, lookup, register versions) Includes schema validation and compatibility checking methods	+350/-0
schemas_pb.d.ts `Schema Registry Protocol Buffer Message Types` packages/db-client/generated/kurrentdb/protocols/v2/registry/schemas_pb.d.ts Generated Protocol Buffer type definitions for schema management messages Defines request/response types for schema CRUD operations and version management Includes `SchemaDetails`, `SchemaVersion`, `RegisteredSchema` message types Supports bulk schema registration with `BulkRegisterSchemasRequest/Response` Provides filtering and metadata capabilities (tags, timestamps, data formats)	+822/-0
groups_pb.d.ts `Schema Registry Group Management Protocol Buffers` packages/db-client/generated/kurrentdb/protocols/v2/registry/groups_pb.d.ts Generated Protocol Buffer definitions for schema group management Defines `SchemaGroup` and `SchemaGroupDetails` message types with configuration Includes settings for auto-registration, validation, compatibility, and data format enforcement Supports stream filtering with regex and category-based filters Provides CRUD operations for schema groups with timestamps and metadata	+474/-0
validation_pb.d.ts `Schema Registry Validation and Compatibility Protocol Buffers` packages/db-client/generated/kurrentdb/protocols/v2/registry/validation_pb.d.ts Generated Protocol Buffer types for schema validation and compatibility checking Defines `CheckSchemaCompatibilityRequest/Response` with success/failure variants Includes `SchemaCompatibilityError` with detailed error information (kind, property path, type changes) Supports compatibility checking against schema names or version IDs Provides comprehensive error reporting for schema validation failures	+247/-0
shared_pb.d.ts `Generated Shared Protocol Buffer Types` packages/db-client/generated/kurrentdb/protocols/v2/registry/shared_pb.d.ts Generated TypeScript type definitions for shared protobuf messages Includes `ErrorDetails` class and schema data format/compatibility mode enums Provides serialization/deserialization methods	+49/-0
service_pb.d.ts `Generated Service Protocol Buffer Types` packages/db-client/generated/kurrentdb/protocols/v2/registry/service_pb.d.ts Generated TypeScript type definitions for gRPC service Imports related protocol buffer definitions for groups, schemas, and validation	+10/-0
errors_pb.d.ts `Generated Error Protocol Buffer Types` packages/db-client/generated/kurrentdb/protocols/v2/registry/errors_pb.d.ts Generated TypeScript type definitions for registry error codes Includes `RegistryError` enum with unspecified default value	+12/-0

Enhancement

24 files

mappers.ts `Schema registry gRPC to domain type mappers` packages/db-client/src/schemaRegistry/utils/mappers.ts Implements bidirectional enum mappers for `SchemaDataFormat`, `CompatibilityMode`, and `SchemaCompatibilityErrorKind` Provides message mapping functions to convert gRPC protobuf objects to TypeScript domain types Includes utility functions for timestamp conversion, map serialization, and schema definition byte handling Exports helper functions to create gRPC schema details from domain objects	+288/-0
index.ts `Schema registry utilities barrel export` packages/db-client/src/schemaRegistry/utils/index.ts Exports all mapper utilities from the mappers module	+1/-0
index.ts `Export schema registry module` packages/db-client/src/index.ts Adds export of `schemaRegistry` module to public API	+1/-0
types.ts `Schema Registry Type Definitions and Interfaces` packages/db-client/src/schemaRegistry/types.ts Defines comprehensive TypeScript types and interfaces for schema registry operations Includes schema data formats (json, protobuf, avro, bytes) and compatibility modes Exports request/response options and result types for all schema registry API operations Defines error types for schema version and compatibility validation	+386/-0
checkSchemaCompatibility.ts `Schema Compatibility Checking Implementation` packages/db-client/src/schemaRegistry/checkSchemaCompatibility.ts Implements `checkSchemaCompatibility` method on the `Client` prototype Validates schema definitions against existing schemas by name or version ID Returns compatibility result with either success (compatible) or failure (errors list) Handles gRPC communication with schema registry service	+105/-0
createSchema.ts `Schema Creation Implementation` packages/db-client/src/schemaRegistry/createSchema.ts Implements `createSchema` method to register new schemas in the registry Supports optional initial schema definition and metadata (description, tags) Returns schema version ID and version number when definition is provided Handles gRPC request/response mapping	+79/-0
updateSchema.ts `Schema Metadata Update Implementation` packages/db-client/src/schemaRegistry/updateSchema.ts Implements `updateSchema` method to modify schema metadata Supports updating description and tags with field mask for selective updates Uses gRPC FieldMask to specify which fields to update Handles schema metadata changes without affecting versions	+86/-0
deleteSchema.ts `Schema Deletion Implementation` packages/db-client/src/schemaRegistry/deleteSchema.ts Implements `deleteSchema` method to remove schemas and all versions Sends delete request to schema registry service via gRPC Returns void on successful deletion	+48/-0
getSchema.ts `Schema Metadata Retrieval Implementation` packages/db-client/src/schemaRegistry/getSchema.ts Implements `getSchema` method to retrieve schema metadata by name Returns schema details including data format, compatibility mode, and timestamps Maps gRPC response to TypeScript `Schema` interface	+57/-0
listSchemas.ts `Schema Listing with Filtering Implementation` packages/db-client/src/schemaRegistry/listSchemas.ts Implements `listSchemas` method with optional filtering by name prefix and tags Returns array of schema metadata matching filter criteria Supports tag-based filtering for schema discovery	+64/-0
lookupSchemaName.ts `Schema Name Lookup by Version ID` packages/db-client/src/schemaRegistry/lookupSchemaName.ts Implements `lookupSchemaName` method to find schema name by version ID Enables reverse lookup from schema version ID to schema name Returns schema name string	+53/-0
registerSchemaVersion.ts `Schema Version Registration Implementation` packages/db-client/src/schemaRegistry/registerSchemaVersion.ts Implements `registerSchemaVersion` method to add new versions to existing schemas Accepts schema definition as string or Uint8Array Returns schema version ID and incremented version number	+69/-0
deleteSchemaVersions.ts `Schema Version Deletion Implementation` packages/db-client/src/schemaRegistry/deleteSchemaVersions.ts Implements `deleteSchemaVersions` method to remove specific schema versions Accepts array of version numbers to delete Returns error list for any failed deletions	+66/-0
getSchemaVersion.ts `Schema Version Retrieval Implementation` packages/db-client/src/schemaRegistry/getSchemaVersion.ts Implements `getSchemaVersion` method to retrieve schema version by name and optional version number Returns latest version when version number is not specified Maps gRPC response to `SchemaVersion` interface	+67/-0
getSchemaVersionById.ts `Schema Version Retrieval by ID Implementation` packages/db-client/src/schemaRegistry/getSchemaVersionById.ts Implements `getSchemaVersionById` method to retrieve schema version by unique ID Enables direct access to specific schema versions via version ID Returns complete schema version details	+60/-0
listSchemaVersions.ts `Schema Versions Listing Implementation` packages/db-client/src/schemaRegistry/listSchemaVersions.ts Implements `listSchemaVersions` method to retrieve all versions of a schema Supports optional inclusion of schema definitions in response Returns array of `SchemaVersion` objects	+60/-0
listRegisteredSchemas.ts `Registered Schemas Listing Implementation` packages/db-client/src/schemaRegistry/listRegisteredSchemas.ts Implements `listRegisteredSchemas` method to list schemas with latest version info Supports filtering by version ID, name prefix, and tags Optionally includes schema definitions in response	+80/-0
index.ts `Schema Registry Module Exports` packages/db-client/src/schemaRegistry/index.ts Exports all schema registry module implementations and types Organizes exports into logical groups: schema management, version management, and compatibility Provides single entry point for schema registry API	+21/-0
shared.proto `Shared Protocol Buffer Definitions` packages/db-client/protos/kurrentdb/protocols/v2/registry/shared.proto Defines shared protobuf enums for schema data formats and compatibility modes Includes `ErrorDetails` message for error information Supports json, protobuf, avro, and bytes data formats Defines 7 compatibility modes from backward to none	+61/-0
schemas.proto `Schema Management Protocol Buffer Definitions` packages/db-client/protos/kurrentdb/protocols/v2/registry/schemas.proto Defines protobuf messages for schema CRUD operations Includes messages for creating, updating, deleting, and listing schemas Defines schema version management messages and registered schema representation Supports bulk registration and field masking for updates	+191/-0
validation.proto `Schema Validation Protocol Buffer Definitions` packages/db-client/protos/kurrentdb/protocols/v2/registry/validation.proto Defines protobuf messages for schema compatibility checking Includes `SchemaCompatibilityError` with detailed error information Defines compatibility error kinds enum with 8 error types Supports success/failure response patterns	+76/-0
groups.proto `Schema Group Management Protocol Buffer Definitions` packages/db-client/protos/kurrentdb/protocols/v2/registry/groups.proto Defines protobuf messages for schema group management Includes settings for auto-registration, validation, compatibility, and data format Supports stream filtering and group CRUD operations Enables hierarchical schema organization	+125/-0
service.proto `Schema Registry gRPC Service Definition` packages/db-client/protos/kurrentdb/protocols/v2/registry/service.proto Defines gRPC service interface for schema registry operations Includes 15 RPC methods for schema and version management Organizes operations into schema groups, schema management, and compatibility sections Supports bulk registration and schema compatibility checking	+61/-0
errors.proto `Schema Registry Error Codes Definition` packages/db-client/protos/kurrentdb/protocols/v2/registry/errors.proto Defines error codes specific to schema registry API Currently contains placeholder for future error code definitions Provides foundation for standardized error handling	+30/-0

Tests

13 files

listRegisteredSchemas.test.ts `Integration Tests for List Registered Schemas` packages/test/src/schemaRegistry/listRegisteredSchemas.test.ts Integration test suite for `listRegisteredSchemas` client method Tests filtering by version ID, name prefix, and schema tags Validates optional schema definition inclusion in responses Verifies correct metadata (version number, data format, compatibility mode, timestamps) Includes edge case testing for non-matching filters	+153/-0
createSchema.test.ts `Schema Creation Integration Tests` packages/test/src/schemaRegistry/createSchema.test.ts Tests schema creation with metadata only and with initial definitions Validates creation with different data formats and tags Tests error handling for duplicate schema names	+114/-0
updateSchema.test.ts `Schema Update Integration Tests` packages/test/src/schemaRegistry/updateSchema.test.ts Tests updating schema description and tags independently Validates combined updates of both description and tags Tests error handling for non-existent schemas	+106/-0
deleteSchema.test.ts `Schema Deletion Integration Tests` packages/test/src/schemaRegistry/deleteSchema.test.ts Tests deletion of schemas with and without versions Validates that deleted schemas cannot be retrieved Tests error handling for non-existent schemas	+79/-0
getSchema.test.ts `Schema Retrieval Integration Tests` packages/test/src/schemaRegistry/getSchema.test.ts Tests retrieval of schema metadata with all properties Validates timestamp population and latest version tracking Tests error handling for non-existent schemas	+93/-0
listSchemas.test.ts `Schema Listing Integration Tests` packages/test/src/schemaRegistry/listSchemas.test.ts Tests listing all schemas and filtering by name prefix Validates tag-based filtering and combined prefix/tag filters Tests empty result handling for non-matching filters	+98/-0
lookupSchemaName.test.ts `Schema Name Lookup Integration Tests` packages/test/src/schemaRegistry/lookupSchemaName.test.ts Tests schema name lookup by version ID from created and registered versions Validates reverse lookup functionality Tests error handling for non-existent version IDs	+77/-0
registerSchemaVersion.test.ts `Schema Version Registration Integration Tests` packages/test/src/schemaRegistry/registerSchemaVersion.test.ts Tests registering new versions for existing schemas Validates version number incrementation Tests registration with Uint8Array definitions	+105/-0
deleteSchemaVersions.test.ts `Schema Version Deletion Integration Tests` packages/test/src/schemaRegistry/deleteSchemaVersions.test.ts Tests deletion of single and multiple schema versions Validates error handling for non-existent versions Tests partial failure scenarios with mixed valid/invalid versions	+142/-0
getSchemaVersion.test.ts `Schema Version Retrieval Integration Tests` packages/test/src/schemaRegistry/getSchemaVersion.test.ts Tests retrieval of latest and specific schema versions Validates schema definition inclusion and timestamp population Tests error handling for non-existent versions and schemas	+151/-0
getSchemaVersionById.test.ts `Schema Version Retrieval by ID Integration Tests` packages/test/src/schemaRegistry/getSchemaVersionById.test.ts Tests retrieval of schema versions by unique ID Validates schema definition content and metadata Tests retrieval of different versions by their IDs	+109/-0
listSchemaVersions.test.ts `Schema Versions Listing Integration Tests` packages/test/src/schemaRegistry/listSchemaVersions.test.ts Tests listing all versions of a schema Validates optional schema definition inclusion Tests version metadata correctness	+126/-0
checkSchemaCompatibility.test.ts `Schema Compatibility Checking Integration Tests` packages/test/src/schemaRegistry/checkSchemaCompatibility.test.ts Tests compatibility checking by schema name and version ID Validates compatible and incompatible definitions with different compatibility modes Tests error details and error handling for non-existent schemas/versions	+249/-0

Additional files

2 files

groups_pb.js	+3593/-0
schemas_pb.js	+6463/-0

qodo-code-review · 2025-12-18T12:50:39Z

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
⚪	Dynamic code evaluation Description: Generated protobuf files use `Function('return this')()` to obtain the global object (also present in other generated files like `.../registry/service_pb.js`), which relies on dynamic code evaluation and may violate CSP policies or enable sandbox escapes in constrained runtimes if this bundle is executed in such environments. validation_pb.js [16-22] Referred Code var global = (function() { if (this) { return this; } if (typeof window !== 'undefined') { return window; } if (typeof global !== 'undefined') { return global; } if (typeof self !== 'undefined') { return self; } return Function('return this')(); }.call(null));
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Logging not visible: The provided diff mostly contains generated gRPC/protobuf bindings and export wiring, and does not show whether schema registry operations add audit logging with user ID, timestamp, action, and outcome. Referred Code export * from "./persistentSubscription"; export * from "./projections"; export * from "./schemaRegistry"; export * from "./streams"; export { Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Error handling unseen: While generated serializers throw on incorrect argument types, the diff does not include the new client method implementations where network/validation edge cases and actionable error contexts would be handled. Referred Code function serialize_kurrentdb_protocol_registry_v2_BulkRegisterSchemasRequest(arg) { if (!(arg instanceof kurrentdb_protocols_v2_registry_schemas_pb.BulkRegisterSchemasRequest)) { throw new Error('Expected argument of type kurrentdb.protocol.registry.v2.BulkRegisterSchemasRequest'); } return Buffer.from(arg.serializeBinary()); } function deserialize_kurrentdb_protocol_registry_v2_BulkRegisterSchemasRequest(buffer_arg) { return kurrentdb_protocols_v2_registry_schemas_pb.BulkRegisterSchemasRequest.deserializeBinary(new Uint8Array(buffer_arg)); } function serialize_kurrentdb_protocol_registry_v2_BulkRegisterSchemasResponse(arg) { if (!(arg instanceof kurrentdb_protocols_v2_registry_schemas_pb.BulkRegisterSchemasResponse)) { throw new Error('Expected argument of type kurrentdb.protocol.registry.v2.BulkRegisterSchemasResponse'); } return Buffer.from(arg.serializeBinary()); } function deserialize_kurrentdb_protocol_registry_v2_BulkRegisterSchemasResponse(buffer_arg) { return kurrentdb_protocols_v2_registry_schemas_pb.BulkRegisterSchemasResponse.deserializeBinary(new Uint8Array(buffer_arg)); } ... (clipped 22 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Error exposure unclear: The generated code throws errors containing internal type names, but the diff does not show whether such errors can propagate to end users versus being wrapped into safer user-facing messages. Referred Code function serialize_kurrentdb_protocol_registry_v2_BulkRegisterSchemasRequest(arg) { if (!(arg instanceof kurrentdb_protocols_v2_registry_schemas_pb.BulkRegisterSchemasRequest)) { throw new Error('Expected argument of type kurrentdb.protocol.registry.v2.BulkRegisterSchemasRequest'); } return Buffer.from(arg.serializeBinary()); } function deserialize_kurrentdb_protocol_registry_v2_BulkRegisterSchemasRequest(buffer_arg) { return kurrentdb_protocols_v2_registry_schemas_pb.BulkRegisterSchemasRequest.deserializeBinary(new Uint8Array(buffer_arg)); } function serialize_kurrentdb_protocol_registry_v2_BulkRegisterSchemasResponse(arg) { if (!(arg instanceof kurrentdb_protocols_v2_registry_schemas_pb.BulkRegisterSchemasResponse)) { throw new Error('Expected argument of type kurrentdb.protocol.registry.v2.BulkRegisterSchemasResponse'); } return Buffer.from(arg.serializeBinary()); } function deserialize_kurrentdb_protocol_registry_v2_BulkRegisterSchemasResponse(buffer_arg) { return kurrentdb_protocols_v2_registry_schemas_pb.BulkRegisterSchemasResponse.deserializeBinary(new Uint8Array(buffer_arg)); } ... (clipped 16 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Logging not shown: The diff does not show any logging additions (structured or otherwise) in the schema registry client operations, so it cannot be validated that logs avoid including schema definitions or other sensitive payloads. Referred Code // source: kurrentdb/protocols/v2/registry/validation.proto /** * @fileoverview * @enhanceable * @suppress {missingRequire} reports error on implicit type usages. * @suppress {messageConventions} JS Compiler reports an error if a variable or * field starts with 'MSG_' and isn't a translatable message. * @public / // GENERATED CODE -- DO NOT EDIT! / eslint-disable */ // @ts-nocheck var jspb = require('google-protobuf'); var goog = jspb; var global = (function() { if (this) { return this; } if (typeof window !== 'undefined') { return window; } if (typeof global !== 'undefined') { return global; } if (typeof self !== 'undefined') { return self; } return Function('return this')(); ... (clipped 14 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Validation not visible: The diff only shows exports for schema registry utilities and generated protocol code, not the schema registry client methods where external input validation, auth/metadata handling, and sensitive data handling would be implemented. Referred Code export * from "./mappers"; Learn more about managing compliance generic rules or creating your own custom rules
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

qodo-code-review · 2025-12-18T12:51:51Z

PR Code Suggestions ✨

Explore these optional code suggestions:

Category Suggestion Impact

High-level

Avoid committing auto-generated code

Instead of committing auto-generated Protobuf/gRPC files, commit the source
.proto files and generate the client code as part of the build process. This
improves reviewability, reduces repository size, and simplifies merges.

Examples:

packages/db-client/generated/kurrentdb/protocols/v2/registry/schemas_pb.js [1-6463]

// source: kurrentdb/protocols/v2/registry/schemas.proto
/**
 * @fileoverview
 * @enhanceable
 * @suppress {missingRequire} reports error on implicit type usages.
 * @suppress {messageConventions} JS Compiler reports an error if a variable or
 *     field starts with 'MSG_' and isn't a translatable message.
 * @public
 */
// GENERATED CODE -- DO NOT EDIT!

 ... (clipped 6453 lines)

packages/db-client/generated/kurrentdb/protocols/v2/registry/groups_pb.js [1-3593]

// source: kurrentdb/protocols/v2/registry/groups.proto
/**
 * @fileoverview
 * @enhanceable
 * @suppress {missingRequire} reports error on implicit type usages.
 * @suppress {messageConventions} JS Compiler reports an error if a variable or
 *     field starts with 'MSG_' and isn't a translatable message.
 * @public
 */
// GENERATED CODE -- DO NOT EDIT!

 ... (clipped 3583 lines)

Solution Walkthrough:

Before:

# .gitignore
# (does not include the 'generated' directory)

# Project Structure
/packages/db-client/
  /generated/
    /kurrentdb/protocols/v2/registry/
      - schemas_pb.js       # Committed to repo
      - groups_pb.js        # Committed to repo
      - service_grpc_pb.js  # Committed to repo
      - ... (many other generated files)
  /src/
    # code uses files from /generated

After:

# .gitignore
/packages/db-client/generated/

# package.json (or similar build config)
"scripts": {
  "build": "generate-proto-clients && other-build-steps",
  "generate-proto-clients": "protoc --proto_path=... --js_out=... --grpc_out=..."
}

# Project Structure
/packages/db-client/
  /protos/
    - schemas.proto       # Source file, committed to repo
    - groups.proto        # Source file, committed to repo
    - service.proto       # Source file, committed to repo
  /generated/             # Excluded from repo via .gitignore
    ...

Suggestion importance[1-10]: 9

__

Why: The suggestion correctly identifies a critical maintainability issue by advising against committing large, auto-generated files, which is a widely accepted best practice.

High

Update

qodo-code-review · 2025-12-18T12:52:46Z

CI Feedback 🧐

(Feedback updated until commit `353a5b9`)

A test triggered by this PR failed. Here is an AI-generated analysis of the failure:

Action: Code quality
Failed stage: All generated code is commited [❌]
Failed test name: ""
Failure summary: The action failed in a “working tree clean” check after the build completed: - After running `git` `update-index --refresh` and `git diff-index --exit-code --name-status HEAD --`, Git reported that `packages/db-client/generated/kurrentdb/protocols/v2/registry/service_grpc_pb.js` “needs update”. - This indicates the build (likely code generation for gRPC/protobuf) modified or regenerated that file, but the updated generated output was not committed in the PR, so the repo had uncommitted changes and the job exited with code 1. Note: The earlier Yarn peer dependency warnings (`@opentelemetry/api` version mismatch and missing `typescript` peer for `ts-jest`) are warnings and do not appear to be the step that caused the failure.
Relevant error logs: 1: ##[group]Runner Image Provisioner 2: Hosted Compute Agent ... 538: �[94m➤�[39m �[90mYN0000�[39m: ┌ Post-resolution validation 539: ##[group]Post-resolution validation 540: �[93m➤�[39m YN0060: │ �[38;5;166m@opentelemetry/�[39m�[38;5;173mapi�[39m is listed by your project with version �[38;5;111m1.9.0�[39m (�[38;5;111mp28b0a�[39m), which doesn't satisfy what �[38;5;166m@opentelemetry/�[39m�[38;5;173mcore�[39m (via �[38;5;166m@opentelemetry/�[39m�[38;5;173mexporter-trace-otlp-grpc�[39m) and other dependencies request (�[38;5;37m>=1.4.0 <1.9.0�[39m). 541: �[93m➤�[39m YN0002: │ �[38;5;173mtest�[39m�[38;5;111m@�[39m�[38;5;111mworkspace:packages/test�[39m doesn't provide �[38;5;173mtypescript�[39m (�[38;5;111mp6f314�[39m), requested by �[38;5;173mts-jest�[39m. 542: �[93m➤�[39m YN0086: │ Some peer dependencies are incorrectly met by your project; run �[38;5;111myarn explain peer-requirements <hash>�[39m for details, where �[38;5;111m<hash>�[39m is the six-letter p-prefixed code. 543: ##[endgroup] 544: �[94m➤�[39m �[90mYN0000�[39m: └ Completed 545: �[94m➤�[39m �[90mYN0000�[39m: ┌ Fetch step 546: ##[group]Fetch step 547: �[94m➤�[39m YN0013: │ �[38;5;220m1138�[39m packages were added to the project (�[38;5;160m+ 300.49 MiB�[39m). 548: ##[endgroup] 549: �[94m➤�[39m �[90mYN0000�[39m: └ Completed in 5s 39ms 550: �[94m➤�[39m �[90mYN0000�[39m: ┌ Link step 551: ##[group]Link step 552: �[93m➤�[39m YN0000: │ ESM support for PnP uses the experimental loader API and is therefore experimental 553: �[94m➤�[39m YN0007: │ �[38;5;173mnx�[39m�[38;5;111m@�[39m�[38;5;111mnpm:20.1.3 [7f914]�[39m must be built because it never has been before or the last one failed 554: �[94m➤�[39m YN0007: │ �[38;5;173mprotobufjs�[39m�[38;5;111m@�[39m�[38;5;111mnpm:7.4.0�[39m must be built because it never has been before or the last one failed 555: �[94m➤�[39m YN0007: │ �[38;5;173mgrpc-tools�[39m�[38;5;111m@�[39m�[38;5;111mnpm:1.13.0�[39m must be built because it never has been before or the last one failed 556: �[94m➤�[39m YN0007: │ �[38;5;173mes5-ext�[39m�[38;5;111m@�[39m�[38;5;111mnpm:0.10.64�[39m must be built because it never has been before or the last one failed 557: �[94m➤�[39m �[90mYN0000�[39m: │ �[38;5;173mgrpc-tools�[39m�[38;5;111m@�[39m�[38;5;111mnpm:1.13.0�[39m �[31mSTDERR�[39m node-pre-gyp info it worked if it ends with ok ... 626: packages/db-client/src/schemaRegistry/getSchemaVersionById.ts 4ms 627: packages/db-client/src/schemaRegistry/index.ts 2ms 628: packages/db-client/src/schemaRegistry/listRegisteredSchemas.ts 5ms 629: packages/db-client/src/schemaRegistry/listSchemas.ts 5ms 630: packages/db-client/src/schemaRegistry/listSchemaVersions.ts 5ms 631: packages/db-client/src/schemaRegistry/lookupSchemaName.ts 5ms 632: packages/db-client/src/schemaRegistry/registerSchemaVersion.ts 7ms 633: packages/db-client/src/schemaRegistry/types.ts 11ms 634: packages/db-client/src/schemaRegistry/updateSchema.ts 8ms 635: packages/db-client/src/schemaRegistry/utils/index.ts 1ms 636: packages/db-client/src/schemaRegistry/utils/mappers.ts 17ms 637: packages/db-client/src/streams/appendToStream/append.ts 18ms 638: packages/db-client/src/streams/appendToStream/batchAppend.ts 15ms 639: packages/db-client/src/streams/appendToStream/index.ts 6ms 640: packages/db-client/src/streams/appendToStream/multiStreamAppend.ts 9ms 641: packages/db-client/src/streams/appendToStream/unpackError.ts 5ms 642: packages/db-client/src/streams/deleteStream.ts 6ms 643: packages/db-client/src/streams/getStreamMetadata.ts 7ms 644: packages/db-client/src/streams/index.ts 3ms 645: packages/db-client/src/streams/readAll.ts 7ms 646: packages/db-client/src/streams/readStream.ts 7ms 647: packages/db-client/src/streams/setStreamMetadata.ts 6ms 648: packages/db-client/src/streams/subscribeToAll.ts 8ms 649: packages/db-client/src/streams/subscribeToStream.ts 6ms 650: packages/db-client/src/streams/tombstoneStream.ts 6ms 651: packages/db-client/src/streams/utils/ReadStream.ts 6ms 652: packages/db-client/src/streams/utils/streamMetadata.ts 12ms 653: packages/db-client/src/streams/utils/Subscription.ts 9ms 654: packages/db-client/src/streams/utils/systemStreams.ts 4ms 655: packages/db-client/src/types/events.ts 11ms 656: packages/db-client/src/types/index.ts 55ms 657: packages/db-client/src/utils/backpressuredWrite.ts 9ms 658: packages/db-client/src/utils/CommandError.ts 63ms 659: packages/db-client/src/utils/convertBridgeError.ts 3ms 660: packages/db-client/src/utils/convertGrpcEvent.ts 14ms 661: packages/db-client/src/utils/convertRustEvent.ts 10ms 662: packages/db-client/src/utils/debug.ts 4ms 663: packages/db-client/src/utils/filter.ts 7ms 664: packages/db-client/src/utils/getGrpcStatusDetails.ts 4ms 665: packages/db-client/src/utils/grpcStreamIdentifier.ts 2ms 666: packages/db-client/src/utils/grpcUUID.ts 3ms 667: packages/db-client/src/utils/index.ts 1ms 668: packages/db-client/src/utils/isClientCancellationError.ts 1ms 669: packages/db-client/src/utils/mapToValue.ts 2ms ... 684: packages/test/src/connection/connectionString/secure-cluster.test.ts 4ms 685: packages/test/src/connection/connectionString/secure-single-node.test.ts 2ms 686: packages/test/src/connection/deadline/deadline-effects.test.ts 5ms 687: packages/test/src/connection/deadline/deadline-settings.test.ts 3ms 688: packages/test/src/connection/defaultCredentials.test.ts 4ms 689: packages/test/src/connection/determineBestNode.test.ts 11ms 690: packages/test/src/connection/dns.test.ts 6ms 691: packages/test/src/connection/insecure.test.ts 3ms 692: packages/test/src/connection/keepAlive.test.ts 14ms 693: packages/test/src/connection/not-leader.test.ts 6ms 694: packages/test/src/connection/parseConnectionString.test.ts 4ms 695: packages/test/src/connection/parseConnectionStringMockups.ts 19ms 696: packages/test/src/connection/reconnect/all-nodes-down.test.ts 12ms 697: packages/test/src/connection/reconnect/mid-stream.test.ts 5ms 698: packages/test/src/connection/reconnect/no-reconnection.test.ts 12ms 699: packages/test/src/connection/reconnect/NotLeaderError.test.ts 5ms 700: packages/test/src/connection/reconnect/UnavailableError.test.ts 6ms 701: packages/test/src/connection/singleNode.test.ts 3ms ... 751: packages/test/src/schemaRegistry/checkSchemaCompatibility.test.ts 16ms 752: packages/test/src/schemaRegistry/createSchema.test.ts 6ms 753: packages/test/src/schemaRegistry/deleteSchema.test.ts 4ms 754: packages/test/src/schemaRegistry/deleteSchemaVersions.test.ts 10ms 755: packages/test/src/schemaRegistry/getSchema.test.ts 11ms 756: packages/test/src/schemaRegistry/getSchemaVersion.test.ts 16ms 757: packages/test/src/schemaRegistry/getSchemaVersionById.test.ts 7ms 758: packages/test/src/schemaRegistry/listRegisteredSchemas.test.ts 10ms 759: packages/test/src/schemaRegistry/listSchemas.test.ts 7ms 760: packages/test/src/schemaRegistry/listSchemaVersions.test.ts 8ms 761: packages/test/src/schemaRegistry/lookupSchemaName.test.ts 4ms 762: packages/test/src/schemaRegistry/registerSchemaVersion.test.ts 6ms 763: packages/test/src/schemaRegistry/updateSchema.test.ts 6ms 764: packages/test/src/streams/appendToStream-batch-append-flood.test.ts 3ms 765: packages/test/src/streams/appendToStream-batch-append.test.ts 8ms 766: packages/test/src/streams/appendToStream-errors.test.ts 9ms 767: packages/test/src/streams/appendToStream.test.ts 37ms ... 808: // 809: // http://www.apache.org/licenses/LICENSE-2.0 810: // 811: // Unless required by applicable law or agreed to in writing, software 812: // distributed under the License is distributed on an "AS IS" BASIS, 813: // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 814: // See the License for the specific language governing permissions and 815: // limitations under the License. 816: syntax = "proto3"; 817: package google.rpc; 818: option go_package = "google.golang.org/genproto/googleapis/rpc/code;code"; 819: option java_multiple_files = true; 820: option java_outer_classname = "CodeProto"; 821: option java_package = "com.google.rpc"; 822: option objc_class_prefix = "RPC"; 823: // The canonical error codes for gRPC APIs. 824: // 825: // 826: // Sometimes multiple error codes may apply. Services should return 827: // the most specific error code that applies. For example, prefer 828: // `OUT_OF_RANGE` over `FAILED_PRECONDITION` if both codes apply. 829: // Similarly prefer `NOT_FOUND` or `ALREADY_EXISTS` over `FAILED_PRECONDITION`. 830: enum Code { 831: // Not an error; returned on success 832: // 833: // HTTP Mapping: 200 OK 834: OK = 0; 835: // The operation was cancelled, typically by the caller. 836: // 837: // HTTP Mapping: 499 Client Closed Request 838: CANCELLED = 1; 839: // Unknown error. For example, this error may be returned when 840: // a `Status` value received from another address space belongs to 841: // an error space that is not known in this address space. Also 842: // errors raised by APIs that do not return enough error information 843: // may be converted to this error. 844: // 845: // HTTP Mapping: 500 Internal Server Error 846: UNKNOWN = 2; 847: // The client specified an invalid argument. Note that this differs 848: // from `FAILED_PRECONDITION`. `INVALID_ARGUMENT` indicates arguments 849: // that are problematic regardless of the state of the system 850: // (e.g., a malformed file name). 851: // 852: // HTTP Mapping: 400 Bad Request 853: INVALID_ARGUMENT = 3; 854: // The deadline expired before the operation could complete. For operations 855: // that change the state of the system, this error may be returned 856: // even if the operation has completed successfully. For example, a ... 865: // of users, such as gradual feature rollout or undocumented whitelist, 866: // `NOT_FOUND` may be used. If a request is denied for some users within 867: // a class of users, such as user-based access control, `PERMISSION_DENIED` 868: // must be used. 869: // 870: // HTTP Mapping: 404 Not Found 871: NOT_FOUND = 5; 872: // The entity that a client attempted to create (e.g., file or directory) 873: // already exists. 874: // 875: // HTTP Mapping: 409 Conflict 876: ALREADY_EXISTS = 6; 877: // The caller does not have permission to execute the specified 878: // operation. `PERMISSION_DENIED` must not be used for rejections 879: // caused by exhausting some resource (use `RESOURCE_EXHAUSTED` 880: // instead for those errors). `PERMISSION_DENIED` must not be 881: // used if the caller can not be identified (use `UNAUTHENTICATED` 882: // instead for those errors). This error code does not imply the 883: // request is valid or the requested entity exists or satisfies ... 889: // operation. 890: // 891: // HTTP Mapping: 401 Unauthorized 892: UNAUTHENTICATED = 16; 893: // Some resource has been exhausted, perhaps a per-user quota, or 894: // perhaps the entire file system is out of space. 895: // 896: // HTTP Mapping: 429 Too Many Requests 897: RESOURCE_EXHAUSTED = 8; 898: // The operation was rejected because the system is not in a state 899: // required for the operation's execution. For example, the directory 900: // to be deleted is non-empty, an rmdir operation is applied to 901: // a non-directory, etc. 902: // 903: // Service implementors can use the following guidelines to decide 904: // between `FAILED_PRECONDITION`, `ABORTED`, and `UNAVAILABLE`: 905: // (a) Use `UNAVAILABLE` if the client can retry just the failing call. 906: // (b) Use `ABORTED` if the client should retry at a higher level 907: // (e.g., when a client-specified test-and-set fails, indicating the 908: // client should restart a read-modify-write sequence). 909: // (c) Use `FAILED_PRECONDITION` if the client should not retry until 910: // the system state has been explicitly fixed. E.g., if an "rmdir" 911: // fails because the directory is non-empty, `FAILED_PRECONDITION` 912: // should be returned since the client should not retry unless 913: // the files are deleted from the directory. 914: // 915: // HTTP Mapping: 400 Bad Request 916: FAILED_PRECONDITION = 9; 917: // The operation was aborted, typically due to a concurrency issue such as 918: // a sequencer check failure or transaction abort. 919: // 920: // See the guidelines above for deciding between `FAILED_PRECONDITION`, 921: // `ABORTED`, and `UNAVAILABLE`. 922: // 923: // HTTP Mapping: 409 Conflict 924: ABORTED = 10; 925: // The operation was attempted past the valid range. E.g., seeking or 926: // reading past end-of-file. 927: // 928: // Unlike `INVALID_ARGUMENT`, this error indicates a problem that may 929: // be fixed if the system state changes. For example, a 32-bit file 930: // system will generate `INVALID_ARGUMENT` if asked to read at an 931: // offset that is not in the range [0,2^32-1], but it will generate 932: // `OUT_OF_RANGE` if asked to read from an offset past the current 933: // file size. 934: // 935: // There is a fair bit of overlap between `FAILED_PRECONDITION` and 936: // `OUT_OF_RANGE`. We recommend using `OUT_OF_RANGE` (the more specific 937: // error) when it applies so that callers who are iterating through 938: // a space can easily look for an `OUT_OF_RANGE` error to detect when 939: // they are done. 940: // 941: // HTTP Mapping: 400 Bad Request 942: OUT_OF_RANGE = 11; 943: // The operation is not implemented or is not supported/enabled in this 944: // service. 945: // 946: // HTTP Mapping: 501 Not Implemented 947: UNIMPLEMENTED = 12; 948: // Internal errors. This means that some invariants expected by the 949: // underlying system have been broken. This error code is reserved 950: // for serious errors. 951: // 952: // HTTP Mapping: 500 Internal Server Error 953: INTERNAL = 13; 954: // The service is currently unavailable. This is most likely a 955: // transient condition, which can be corrected by retrying with 956: // a backoff. Note that it is not always safe to retry 957: // non-idempotent operations. 958: // 959: // See the guidelines above for deciding between `FAILED_PRECONDITION`, 960: // `ABORTED`, and `UNAVAILABLE`. 961: // 962: // HTTP Mapping: 503 Service Unavailable 963: UNAVAILABLE = 14; 964: // Unrecoverable data loss or corruption. 965: // 966: // HTTP Mapping: 500 Internal Server Error 967: DATA_LOSS = 15; ... 1593: // Unless required by applicable law or agreed to in writing, software 1594: // distributed under the License is distributed on an "AS IS" BASIS, 1595: // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 1596: // See the License for the specific language governing permissions and 1597: // limitations under the License. 1598: syntax = "proto3"; 1599: package google.rpc; 1600: import "google/protobuf/any.proto"; 1601: import "kurrentdb/protocols/v1/code.proto"; 1602: option cc_enable_arenas = true; 1603: option go_package = "google.golang.org/genproto/googleapis/rpc/status;status"; 1604: option java_multiple_files = true; 1605: option java_outer_classname = "StatusProto"; 1606: option java_package = "com.google.rpc"; 1607: option objc_class_prefix = "RPC"; 1608: // The `Status` type defines a logical error model that is suitable for 1609: // different programming environments, including REST APIs and RPC APIs. It is 1610: // used by [gRPC](https://github.com/grpc). Each `Status` message contains 1611: // three pieces of data: error code, error message, and error details. 1612: // 1613: // You can find out more about this error model and how to work with it in the 1614: // [API Design Guide](https://cloud.google.com/apis/design/errors). 1615: message Status { 1616: // The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 1617: google.rpc.Code code = 1; 1618: // A developer-facing error message, which should be in English. Any 1619: // user-facing error message should be localized and sent in the 1620: // [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 1621: string message = 2; 1622: // A list of messages that carry the error details. There is a common set of 1623: // message types for APIs to use. ... 1859: oneof deadline_option { 1860: google.protobuf.Timestamp deadline_21_10_0 = 6; 1861: google.protobuf.Duration deadline = 7; 1862: } 1863: } 1864: message ProposedMessage { 1865: event_store.client.UUID id = 1; 1866: map<string, string> metadata = 2; 1867: bytes custom_metadata = 3; 1868: bytes data = 4; 1869: } 1870: } 1871: message BatchAppendResp { 1872: event_store.client.UUID correlation_id = 1; 1873: oneof result { 1874: google.rpc.Status error = 2; 1875: Success success = 3; ... 2026: } 2027: message ResetPasswordReq { 2028: Options options = 1; 2029: message Options { 2030: string login_name = 1; 2031: string new_password = 2; 2032: } 2033: } 2034: message ResetPasswordResp { 2035: } 2036: // **************************************************************************************** 2037: // This protocol is UNSTABLE in the sense of being subject to change. 2038: // ************************************************************************************** 2039: syntax = "proto3"; 2040: package kurrent.rpc; 2041: option csharp_namespace = "KurrentDB.Protocol.V2.Common.Errors"; 2042: import "kurrentdb/protocols/v2/rpc.proto"; 2043: // The canonical server error codes for the Kurrent Platform gRPC APIs. 2044: // These errors represent common failure modes across all Kurrent services. 2045: enum ServerError { 2046: // Default value. This value is not used. 2047: // An error code MUST always be set to a non-zero value. 2048: // If an error code is not explicitly set, it MUST be treated as 2049: // an internal server error (INTERNAL). 2050: UNSPECIFIED = 0; 2051: // Authentication or authorization failure. 2052: // The client lacks valid credentials or sufficient permissions to perform the requested operation. 2053: // 2054: // Common causes: 2055: // - Missing or invalid authentication tokens 2056: // - Insufficient permissions for the operation 2057: // - Expired credentials 2058: // 2059: // Client action: Check credentials, verify permissions, and re-authenticate if necessary. 2060: // Not retriable without fixing the underlying authorization issue. 2061: SERVER_ERROR_ACCESS_DENIED = 1 [(kurrent.rpc.error) = { 2062: status_code: PERMISSION_DENIED, 2063: has_details: true 2064: }]; 2065: // The request is malformed or contains invalid data. 2066: // The server cannot process the request due to client error. 2067: // 2068: // Common causes: 2069: // - Invalid field values (e.g., empty required fields, out-of-range numbers) 2070: // - Malformed data formats 2071: // - Validation failures 2072: // 2073: // Client action: Fix the request data and retry. 2074: // Not retriable without modifying the request. 2075: SERVER_ERROR_BAD_REQUEST = 2 [(kurrent.rpc.error) = { 2076: status_code: INVALID_ARGUMENT, 2077: has_details: true 2078: }]; 2079: // The server is not the cluster leader and cannot process write operations. 2080: // In a clustered deployment, only the leader node can accept write operations. 2081: // 2082: // Common causes: 2083: // - Client connected to a follower node 2084: // - Leader election in progress 2085: // - Network partition 2086: // 2087: // Client action: Redirect the request to the leader node indicated in the error details. 2088: // Retriable after redirecting to the correct leader node. 2089: SERVER_ERROR_NOT_LEADER_NODE = 5 [(kurrent.rpc.error) = { 2090: status_code: FAILED_PRECONDITION, 2091: has_details: true 2092: }]; 2093: // The operation did not complete within the configured timeout period. 2094: // 2095: // Common causes: 2096: // - Slow disk I/O during writes 2097: // - Cluster consensus delays 2098: // - Network latency 2099: // - Heavy server load 2100: // 2101: // Client action: Retry with exponential backoff. Consider increasing timeout values. 2102: // Retriable - the operation may succeed on retry. 2103: SERVER_ERROR_OPERATION_TIMEOUT = 6 [(kurrent.rpc.error) = { 2104: status_code: DEADLINE_EXCEEDED 2105: }]; 2106: // The server is starting up or shutting down and cannot process requests. 2107: // 2108: // Common causes: 2109: // - Server is initializing (loading indexes, recovering state) 2110: // - Server is performing graceful shutdown 2111: // - Server is performing maintenance operations 2112: // 2113: // Client action: Retry with exponential backoff. Wait for server to become ready. 2114: // Retriable - the server will become available after initialization completes. 2115: SERVER_ERROR_SERVER_NOT_READY = 7 [(kurrent.rpc.error) = { 2116: status_code: UNAVAILABLE 2117: }]; 2118: // The server is temporarily overloaded and cannot accept more requests. 2119: // This is a backpressure mechanism to prevent server overload. 2120: // 2121: // Common causes: 2122: // - Too many concurrent requests 2123: // - Resource exhaustion (CPU, memory, disk I/O) 2124: // - Rate limiting triggered 2125: // 2126: // Client action: Retry with exponential backoff. Reduce request rate. 2127: // Retriable - the server may accept requests after load decreases. 2128: SERVER_ERROR_SERVER_OVERLOADED = 8 [(kurrent.rpc.error) = { 2129: status_code: UNAVAILABLE 2130: }]; 2131: // An internal server error occurred. 2132: // This indicates a bug or unexpected condition in the server. 2133: // 2134: // Common causes: 2135: // - Unhandled exceptions 2136: // - Assertion failures 2137: // - Corrupted internal state 2138: // - Programming errors 2139: // 2140: // Client action: Report to server administrators with request details. 2141: // May be retriable, but likely indicates a server-side issue requiring investigation. 2142: SERVER_ERROR_SERVER_MALFUNCTION = 9 [(kurrent.rpc.error) = { 2143: status_code: INTERNAL 2144: }]; 2145: } 2146: // Details for ACCESS_DENIED errors. 2147: message AccessDeniedErrorDetails { 2148: // The friendly name of the operation that was denied. 2149: string operation = 1; 2150: // The username of the user who was denied access. 2151: optional string username = 2; 2152: // The permission that was required for this operation. 2153: optional string permission = 3; 2154: } 2155: // Details for NOT_LEADER_NODE errors. 2156: message NotLeaderNodeErrorDetails { 2157: // Information about the current cluster leader node. 2158: NodeInfo current_leader = 1; 2159: // Information about a cluster node. 2160: message NodeInfo { 2161: // The hostname or IP address of the node. 2162: string host = 1; 2163: // The gRPC port of the node. 2164: int32 port = 2; 2165: // The unique instance ID of the node. 2166: optional string node_id = 3; 2167: } 2168: } 2169: // ************************************************************************************** 2170: // This protocol is UNSTABLE in the sense of being subject to change. 2171: // ************************************************************************************** 2172: syntax = "proto3"; 2173: package kurrentdb.protocol.v2.registry.errors; 2174: option csharp_namespace = "KurrentDB.Protocol.V2.Registry.Errors"; 2175: import "kurrentdb/protocols/v2/rpc.proto"; 2176: // Error codes specific to the Schema Registry API. 2177: enum RegistryError { 2178: // Default value. This value is not used. 2179: // An error code MUST always be set to a non-zero value. 2180: // If an error code is not explicitly set, it MUST be treated as 2181: // an internal server error (INTERNAL). 2182: REGISTRY_ERROR_UNSPECIFIED = 0; 2183: // // The specified schema could not be found. Please check the schema name and try again. 2184: // REGISTRY_ERROR_NOT_FOUND = 1 [(kurrent.rpc.error) = { 2185: // status_code: NOT_FOUND 2186: // }]; 2187: // 2188: // // The specified schema has already been created and cannot be created again. Please use a different name. 2189: // REGISTRY_ERROR_ALREADY_EXISTS = 2 [(kurrent.rpc.error) = { 2190: // status_code: ALREADY_EXISTS ... 2365: string schema_name = 1; 2366: } 2367: message RegisterSchemaVersionRequest { 2368: string schema_name = 1; 2369: bytes schema_definition = 2; 2370: } 2371: message RegisterSchemaVersionResponse { 2372: string schema_version_id = 1; 2373: int32 version_number = 2; 2374: } 2375: message DeleteSchemaVersionsRequest { 2376: string schema_name = 1; 2377: repeated int32 versions = 2; 2378: } 2379: message DeleteSchemaVersionsResponse { 2380: repeated SchemaVersionError errors = 1; 2381: message SchemaVersionError { 2382: int32 version_number = 1; 2383: ErrorDetails error = 2; 2384: } ... 2426: // The unique identifier of the schema version. If specified, only the schema with the specified version ID is returned. 2427: optional string schema_version_id = 1; 2428: // The prefix of the schema name. If specified, only schemas with the specified prefix are returned. 2429: optional string schema_name_prefix = 2; 2430: // The tags to filter the schemas. If specified, only schemas with the specified tags are returned. 2431: map<string, string> schema_tags = 3; 2432: // If true, the schema definition will be included in the response. 2433: bool include_definition = 4; 2434: } 2435: message ListRegisteredSchemasResponse { 2436: repeated RegisteredSchema schemas = 1; 2437: } 2438: message BulkRegisterSchemasRequest { 2439: repeated CreateSchemaRequest requests = 1; 2440: bool keep_order = 2; 2441: bool stop_on_error = 3; 2442: } ... 2471: rpc RegisterSchemaVersion(RegisterSchemaVersionRequest) returns (RegisterSchemaVersionResponse); 2472: rpc DeleteSchemaVersions(DeleteSchemaVersionsRequest) returns (DeleteSchemaVersionsResponse); 2473: rpc GetSchemaVersion(GetSchemaVersionRequest) returns (GetSchemaVersionResponse); // produce 2474: rpc GetSchemaVersionById(GetSchemaVersionByIdRequest) returns (GetSchemaVersionByIdResponse); 2475: rpc ListSchemaVersions(ListSchemaVersionsRequest) returns (ListSchemaVersionsResponse); 2476: rpc ListRegisteredSchemas(ListRegisteredSchemasRequest) returns (ListRegisteredSchemasResponse); 2477: rpc BulkRegisterSchemas(BulkRegisterSchemasRequest) returns (BulkRegisterSchemasResponse); 2478: //=================================================================== 2479: // Schema Compatibility & Validation 2480: //=================================================================== 2481: rpc CheckSchemaCompatibility(CheckSchemaCompatibilityRequest) returns (CheckSchemaCompatibilityResponse); // consume 2482: } 2483: syntax = "proto3"; 2484: package kurrentdb.protocol.registry.v2; 2485: option csharp_namespace = "KurrentDB.Protocol.V2.Registry"; 2486: message ErrorDetails { 2487: string code = 1; // Standardized string to programmatically identify the error. 2488: string message = 2; // Detailed error description and debugging information. 2489: } ... 2521: COMPATIBILITY_MODE_BACKWARD_ALL = 4; 2522: // Forward All compatibility ensures ALL previous schema versions can read data written by new schemas. 2523: // This provides stronger guarantees than regular forward compatibility. 2524: COMPATIBILITY_MODE_FORWARD_ALL = 5; 2525: // Full All compatibility combines backward all and forward all compatibility modes. 2526: // This ensures complete compatibility across all schema versions, providing the strongest compatibility guarantees. 2527: COMPATIBILITY_MODE_FULL_ALL = 6; 2528: // Disables compatibility checks, allowing any kind of schema change. 2529: // This mode should be used with caution, as it may lead to compatibility issues. 2530: COMPATIBILITY_MODE_NONE = 7; 2531: } 2532: syntax = "proto3"; 2533: package kurrentdb.protocol.registry.v2; 2534: option csharp_namespace = "KurrentDB.Protocol.V2.Registry"; 2535: import "kurrentdb/protocols/v2/registry/shared.proto"; 2536: // Represents a schema compatibility error. 2537: message SchemaCompatibilityError { 2538: SchemaCompatibilityErrorKind kind = 1; // The type of compatibility error. 2539: string details = 2; // The error message 2540: optional string property_path = 3; // The path to the property where the compatibility error occurred. 2541: optional string original_type = 4; // The type of property in the registered schema (e.g. array, bool, number, object) 2542: optional string new_type = 5; // The type of property in the schema being validated (e.g. array, bool, number, object) 2543: } 2544: // Represents the result of schema compatibility, containing a list of compatibility errors. 2545: message SchemaCompatibilityResult { 2546: // Indicates whether the schema is compatible with the registered schema. 2547: bool is_compatible = 1; 2548: // The schema identifier of the schema being validated. 2549: string schema_version_id = 2; 2550: // A list of schema compatibility errors. 2551: repeated SchemaCompatibilityError errors = 3; 2552: } 2553: message CheckSchemaCompatibilityRequest { 2554: oneof schema_identifier { 2555: string schema_name = 1; 2556: string schema_version_id = 2; 2557: } 2558: bytes definition = 3; 2559: SchemaDataFormat data_format = 4; 2560: } 2561: message CheckSchemaCompatibilityResponse { 2562: //SchemaCompatibilityResult result = 1; 2563: oneof result { 2564: Success success = 1; 2565: Failure failure = 2; 2566: } 2567: // Indicates whether the schema is compatible with the registered schema. 2568: message Success { 2569: // The schema identifier of the schema being validated. 2570: string schema_version_id = 2; 2571: } 2572: message Failure { 2573: // A list of schema compatibility errors. 2574: repeated SchemaCompatibilityError errors = 3; 2575: } 2576: } 2577: // Enum representing different kinds of compatibility errors. 2578: enum SchemaCompatibilityErrorKind { 2579: SCHEMA_COMPATIBILITY_ERROR_KIND_UNSPECIFIED = 0; // Default value, do not use. 2580: SCHEMA_COMPATIBILITY_ERROR_KIND_MISSING_REQUIRED_PROPERTY = 1; // Backward compatibility: Required property from old schema missing in new schema 2581: SCHEMA_COMPATIBILITY_ERROR_KIND_INCOMPATIBLE_TYPE_CHANGE = 2; // Backward compatibility: Property type changed incompatibly 2582: SCHEMA_COMPATIBILITY_ERROR_KIND_OPTIONAL_TO_REQUIRED = 3; // Backward compatibility: Property changed from optional to required 2583: SCHEMA_COMPATIBILITY_ERROR_KIND_NEW_REQUIRED_PROPERTY = 4; // Forward compatibility: New required property added 2584: SCHEMA_COMPATIBILITY_ERROR_KIND_REMOVED_PROPERTY = 5; // Forward compatibility: Property removed from schema 2585: SCHEMA_COMPATIBILITY_ERROR_KIND_ARRAY_TYPE_INCOMPATIBILITY = 6; // Issues with array item types 2586: SCHEMA_COMPATIBILITY_ERROR_KIND_DATA_FORMAT_MISMATCH = 7; // Data format mismatch between schemas 2587: } 2588: // Represents the information necessary to check schema compatibility or validate a schema. 2589: message SchemaValidationInfo { 2590: string schema_version_id = 1; 2591: bytes schema_definition = 2; 2592: SchemaDataFormat data_format = 3; 2593: CompatibilityMode compatibility = 4; 2594: } 2595: // ************************************************************************************** 2596: // This protocol is UNSTABLE in the sense of being subject to change. 2597: // ************************************************************************************** 2598: syntax = "proto3"; 2599: package kurrent.rpc; 2600: option csharp_namespace = "Kurrent.Rpc"; 2601: import "google/protobuf/descriptor.proto"; 2602: import "kurrentdb/protocols/v1/code.proto"; 2603: // ErrorMetadata provides actionable information for error enum values to enable automated 2604: // code generation, documentation, and consistent error handling across the Kurrent platform. 2605: // 2606: // It was modeled to support a single details type per error code to simplify code generation and 2607: // validation. If multiple detail types are needed for a single error code, consider defining 2608: // separate error codes for each detail type. Or, use a union type (oneof) in the detail message 2609: // to encapsulate multiple detail variants within a single detail message. 2610: // 2611: // More however DebugInfo and RetryInfo can and should be added to any error regardless of 2612: // this setting, when applicable. 2613: // 2614: // This annotation is applied to enum values using the google.protobuf.EnumValueOptions 2615: // extension mechanism. It enables: 2616: // - Automatic gRPC status code mapping 2617: // - Code generation for error handling utilities 2618: // - Documentation generation 2619: // - Type-safe error detail validation 2620: // 2621: // Usage Example: 2622: // enum StreamErrorCode { 2623: // REVISION_CONFLICT = 5 [(kurrent.rpc.error) = { 2624: // status_code: FAILED_PRECONDITION, 2625: // has_details: true 2626: // }]; 2627: // } 2628: // 2629: // See individual field documentation for conventions and defaults. 2630: message ErrorMetadata { 2631: // Maps the error to a standard gRPC status code for transport-level compatibility. 2632: // This field is REQUIRED for every error annotation. 2633: // 2634: // Use standard gRPC status codes from `google.rpc.code`. 2635: // 2636: // Code generators use this to: 2637: // - Map errors to gRPC status codes automatically 2638: // - Generate HTTP status code mappings 2639: // - Create transport-agnostic error handling 2640: google.rpc.Code status_code = 1; 2641: // Indicates whether this error supports rich, typed detail messages. 2642: // Defaults to false (simple message string only). 2643: // The message type name must be derived from the enum name by convention. 2644: // Mask: {EnumValue}ErrorDetails, {EnumValue}Error, {EnumValue} 2645: // 2646: // Examples: 2647: // ACCESS_DENIED -> "AccessDeniedErrorDetails", "AccessDeniedError" or "AccessDenied" 2648: // SERVER_NOT_READY -> "ServerNotReadyErrorDetails", "ServerNotReadyError" or "ServerNotReady" 2649: // 2650: // Code generators use the message type name to: 2651: // - Validate that the detail message matches the expected type 2652: // - Generate type-safe error handling code 2653: // - Create accurate documentation 2654: bool has_details = 2; 2655: } 2656: // Extend EnumValueOptions to include error information for enum values 2657: extend google.protobuf.EnumValueOptions { 2658: // Provides additional information about error conditions for automated 2659: // code generation and documentation. 2660: optional ErrorMetadata error = 50000; 2661: } 2662: // ************************************************************************************** 2663: // This protocol is UNSTABLE in the sense of being subject to change. 2664: // ************************************************************************************** 2665: syntax = "proto3"; 2666: package kurrentdb.protocol.v2.streams.errors; 2667: option csharp_namespace = "KurrentDB.Protocol.V2.Streams.Errors"; 2668: import "kurrentdb/protocols/v2/rpc.proto"; 2669: // Error codes specific to the Streams API. 2670: // These errors represent failure modes when working with streams of records. 2671: enum StreamsError { 2672: // Default value. This value is not used. 2673: // An error code MUST always be set to a non-zero value. 2674: // If an error code is not explicitly set, it MUST be treated as 2675: // an internal server error (INTERNAL). 2676: STREAMS_ERROR_UNSPECIFIED = 0; 2677: // The requested stream does not exist in the database. 2678: // 2679: // Common causes: 2680: // - Stream name typo or incorrect stream identifier 2681: // - Stream was never created (no events appended yet) 2682: // - Stream was deleted and not yet recreated 2683: // 2684: // Client action: Verify the stream name is correct. Create the stream by appending to it. 2685: // Recoverable by creating the stream first (append with NO_STREAM expected revision). 2686: STREAMS_ERROR_STREAM_NOT_FOUND = 1 [(kurrent.rpc.error) = { 2687: status_code: NOT_FOUND, 2688: has_details: true, 2689: }]; 2690: // The stream already exists when an operation expected it not to exist. 2691: // 2692: // Common causes: 2693: // - Attempting to create a stream that already has events 2694: // - Using NO_STREAM expected revision on an existing stream 2695: // - Race condition with concurrent stream creation 2696: // 2697: // Client action: Use the existing stream or use a different expected revision. 2698: // Recoverable by adjusting the expected revision or using the existing stream. 2699: STREAMS_ERROR_STREAM_ALREADY_EXISTS = 2 [(kurrent.rpc.error) = { 2700: status_code: ALREADY_EXISTS, 2701: has_details: true 2702: }]; 2703: // The stream has been soft deleted. 2704: // Soft-deleted streams are hidden from stream lists but can be restored by appending to them. 2705: // 2706: // Common causes: 2707: // - Stream was explicitly soft-deleted via delete operation 2708: // - Attempting to read from a soft-deleted stream 2709: // 2710: // Client action: Restore the stream by appending new events, or accept that the stream is deleted. 2711: // Recoverable by appending to the stream to restore it. 2712: STREAMS_ERROR_STREAM_DELETED = 3 [(kurrent.rpc.error) = { 2713: status_code: FAILED_PRECONDITION, 2714: has_details: true 2715: }]; 2716: // The stream has been tombstoned (permanently deleted). 2717: // Tombstoned streams cannot be restored and will never accept new events. 2718: // 2719: // Common causes: 2720: // - Stream was explicitly tombstoned via tombstone operation 2721: // - Administrative deletion of sensitive data 2722: // - Attempting to write to or read from a tombstoned stream 2723: // 2724: // Client action: Stream is permanently removed. Create a new stream with a different name if needed. 2725: // Not recoverable - the stream cannot be restored. 2726: STREAMS_ERROR_STREAM_TOMBSTONED = 4 [(kurrent.rpc.error) = { 2727: status_code: FAILED_PRECONDITION, 2728: has_details: true 2729: }]; 2730: // The expected revision does not match the actual stream revision. 2731: // This is an optimistic concurrency control failure. 2732: // 2733: // Common causes: 2734: // - Another client modified the stream concurrently 2735: // - Client has stale state about the stream revision 2736: // - Race condition in distributed system 2737: // 2738: // Client action: Fetch the current stream revision and retry with the correct expected revision. 2739: // Recoverable by reading the current state and retrying with proper optimistic concurrency control. 2740: STREAMS_ERROR_STREAM_REVISION_CONFLICT = 5 [(kurrent.rpc.error) = { 2741: status_code: FAILED_PRECONDITION, 2742: has_details: true 2743: }]; 2744: // A single record being appended exceeds the maximum allowed size. 2745: // 2746: // Common causes: 2747: // - Record payload is too large (exceeds server's max record size configuration) 2748: // - Excessive metadata in properties 2749: // - Large binary data without chunking 2750: // 2751: // Client action: Reduce record size, split large payloads across multiple records, or increase server limits. 2752: // Recoverable by reducing record size or adjusting server configuration. 2753: STREAMS_ERROR_APPEND_RECORD_SIZE_EXCEEDED = 6 [(kurrent.rpc.error) = { 2754: status_code: INVALID_ARGUMENT, 2755: has_details: true 2756: }]; 2757: // The total size of all records in a single append session exceeds the maximum allowed transaction size. 2758: // 2759: // Common causes: 2760: // - Too many records in a single append session 2761: // - Combined payload size exceeds server's max transaction size 2762: // - Attempting to write very large batches 2763: // 2764: // Client action: Split the append into multiple smaller transactions. 2765: // Recoverable by reducing the number of records per append session. 2766: STREAMS_ERROR_APPEND_TRANSACTION_SIZE_EXCEEDED = 7 [(kurrent.rpc.error) = { 2767: status_code: ABORTED, 2768: has_details: true 2769: }]; 2770: // The same stream appears multiple times in a single append session. 2771: // This is currently not supported to prevent complexity with expected revisions and ordering. 2772: // 2773: // Common causes: 2774: // - Accidentally appending to the same stream twice in one session 2775: // - Application logic error in batch operations 2776: // 2777: // Client action: Remove duplicate streams from the append session or split into multiple sessions. 2778: // Recoverable by restructuring the append session to reference each stream only once. 2779: STREAMS_ERROR_STREAM_ALREADY_IN_APPEND_SESSION = 8 [(kurrent.rpc.error) = { 2780: status_code: ABORTED, 2781: has_details: true 2782: }]; 2783: // An append session was started but no append requests were sent before completing the stream. 2784: // 2785: // Common causes: 2786: // - Client completed the stream without sending any AppendRequest messages 2787: // - Application logic error 2788: // 2789: // Client action: Ensure at least one AppendRequest is sent before completing the stream. 2790: // Recoverable by properly implementing the append session protocol. 2791: STREAMS_ERROR_APPEND_SESSION_NO_REQUESTS = 9 [(kurrent.rpc.error) = { 2792: status_code: FAILED_PRECONDITION 2793: }]; 2794: } 2795: // Details for STREAM_NOT_FOUND errors. 2796: message StreamNotFoundErrorDetails { 2797: // The name of the stream that was not found. 2798: string stream = 1; 2799: } 2800: // Details for STREAM_ALREADY_EXISTS errors. 2801: message StreamAlreadyExistsErrorDetails { 2802: // The name of the stream that already exists. 2803: string stream = 1; 2804: } 2805: // Details for STREAM_DELETED errors. 2806: message StreamDeletedErrorDetails { 2807: // The name of the stream that was deleted. 2808: string stream = 1; 2809: } 2810: // Details for STREAM_TOMBSTONED errors. 2811: message StreamTombstonedErrorDetails { 2812: // The name of the stream that was tombstoned. 2813: string stream = 1; 2814: } 2815: // Details for STREAM_REVISION_CONFLICT errors. 2816: message StreamRevisionConflictErrorDetails { 2817: // The name of the stream that had a revision conflict. 2818: string stream = 1; 2819: // The expected revision that was provided in the append request. 2820: sint64 expected_revision = 2 [jstype = JS_STRING]; 2821: // The actual current revision of the stream. 2822: sint64 actual_revision = 3 [jstype = JS_STRING]; 2823: } 2824: // Details for APPEND_RECORD_SIZE_EXCEEDED errors. 2825: message AppendRecordSizeExceededErrorDetails { 2826: // The name of the stream where the append was attempted. 2827: string stream = 1; 2828: // The identifier of the record that exceeded the size limit. 2829: string record_id = 2; 2830: // The actual size of the record in bytes. 2831: int32 size = 3; 2832: // The maximum allowed size of a single record in bytes. 2833: int32 max_size = 4; 2834: } 2835: // Details for APPEND_TRANSACTION_SIZE_EXCEEDED errors. 2836: message AppendTransactionSizeExceededErrorDetails { 2837: // The actual size of the transaction in bytes. 2838: int32 size = 1; 2839: // The maximum allowed size of an append transaction in bytes. 2840: int32 max_size = 2; 2841: } 2842: // Details for STREAM_ALREADY_IN_APPEND_SESSION errors. 2843: message StreamAlreadyInAppendSessionErrorDetails { 2844: // The name of the stream that appears multiple times. ... 2846: } 2847: // ************************************************************************************** 2848: // This protocol is UNSTABLE in the sense of being subject to change. 2849: // ************************************************************************************** 2850: syntax = "proto3"; 2851: package kurrentdb.protocol.v2.streams; 2852: option csharp_namespace = "KurrentDB.Protocol.V2.Streams"; 2853: import "google/protobuf/struct.proto"; 2854: service StreamsService { 2855: // Appends records to multiple streams atomically within a single transaction. 2856: // 2857: // This is a client-streaming RPC where the client sends multiple AppendRequest messages 2858: // (one per stream) and receives a single AppendSessionResponse upon commit. 2859: // 2860: // Guarantees: 2861: // - Atomicity: All writes succeed or all fail together 2862: // - Optimistic Concurrency: Expected revisions are validated for all streams before commit ... 2953: // - "$timestamp": "2025-01-15T10:30:00.000Z" // ISO 8601 timestamp 2954: map<string, google.protobuf.Value> properties = 2; 2955: // Schema information for this record. 2956: SchemaInfo schema = 3; 2957: // The record payload as raw bytes. 2958: // The format specified in SchemaInfo determines how to interpret these bytes. 2959: bytes data = 4; 2960: } 2961: // Constants for expected revision validation in optimistic concurrency control. 2962: // These can be used in the expected_revision field, or you can specify an actual revision number. 2963: enum ExpectedRevisionConstants { 2964: // The stream must have exactly one event at revision 0. 2965: // Used for scenarios requiring strict single-event semantics. 2966: EXPECTED_REVISION_CONSTANTS_SINGLE_EVENT = 0; 2967: // The stream must not exist yet (first write to the stream). 2968: // Fails if the stream already has events. 2969: EXPECTED_REVISION_CONSTANTS_NO_STREAM = -1; 2970: // Accept any current state of the stream (no optimistic concurrency check). 2971: // The write will succeed regardless of the stream's current revision. 2972: EXPECTED_REVISION_CONSTANTS_ANY = -2; 2973: // The stream must exist (have at least one record). 2974: // Fails if the stream doesn't exist yet. 2975: EXPECTED_REVISION_CONSTANTS_EXISTS = -4; ... 2981: // 2982: // http://www.apache.org/licenses/LICENSE-2.0 2983: // 2984: // Unless required by applicable law or agreed to in writing, software 2985: // distributed under the License is distributed on an "AS IS" BASIS, 2986: // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 2987: // See the License for the specific language governing permissions and 2988: // limitations under the License. 2989: syntax = "proto3"; 2990: package google.rpc; 2991: option go_package = "google.golang.org/genproto/googleapis/rpc/code;code"; 2992: option java_multiple_files = true; 2993: option java_outer_classname = "CodeProto"; 2994: option java_package = "com.google.rpc"; 2995: option objc_class_prefix = "RPC"; 2996: // The canonical error codes for gRPC APIs. 2997: // 2998: // 2999: // Sometimes multiple error codes may apply. Services should return 3000: // the most specific error code that applies. For example, prefer 3001: // `OUT_OF_RANGE` over `FAILED_PRECONDITION` if both codes apply. 3002: // Similarly prefer `NOT_FOUND` or `ALREADY_EXISTS` over `FAILED_PRECONDITION`. 3003: enum Code { 3004: // Not an error; returned on success 3005: // 3006: // HTTP Mapping: 200 OK 3007: OK = 0; 3008: // The operation was cancelled, typically by the caller. 3009: // 3010: // HTTP Mapping: 499 Client Closed Request 3011: CANCELLED = 1; 3012: // Unknown error. For example, this error may be returned when 3013: // a `Status` value received from another address space belongs to 3014: // an error space that is not known in this address space. Also 3015: // errors raised by APIs that do not return enough error information 3016: // may be converted to this error. 3017: // 3018: // HTTP Mapping: 500 Internal Server Error 3019: UNKNOWN = 2; 3020: // The client specified an invalid argument. Note that this differs 3021: // from `FAILED_PRECONDITION`. `INVALID_ARGUMENT` indicates arguments 3022: // that are problematic regardless of the state of the system 3023: // (e.g., a malformed file name). 3024: // 3025: // HTTP Mapping: 400 Bad Request 3026: INVALID_ARGUMENT = 3; 3027: // The deadline expired before the operation could complete. For operations 3028: // that change the state of the system, this error may be returned 3029: // even if the operation has completed successfully. For example, a ... 3038: // of users, such as gradual feature rollout or undocumented whitelist, 3039: // `NOT_FOUND` may be used. If a request is denied for some users within 3040: // a class of users, such as user-based access control, `PERMISSION_DENIED` 3041: // must be used. 3042: // 3043: // HTTP Mapping: 404 Not Found 3044: NOT_FOUND = 5; 3045: // The entity that a client attempted to create (e.g., file or directory) 3046: // already exists. 3047: // 3048: // HTTP Mapping: 409 Conflict 3049: ALREADY_EXISTS = 6; 3050: // The caller does not have permission to execute the specified 3051: // operation. `PERMISSION_DENIED` must not be used for rejections 3052: // caused by exhausting some resource (use `RESOURCE_EXHAUSTED` 3053: // instead for those errors). `PERMISSION_DENIED` must not be 3054: // used if the caller can not be identified (use `UNAUTHENTICATED` 3055: // instead for those errors). This error code does not imply the 3056: // request is valid or the requested entity exists or satisfies ... 3062: // operation. 3063: // 3064: // HTTP Mapping: 401 Unauthorized 3065: UNAUTHENTICATED = 16; 3066: // Some resource has been exhausted, perhaps a per-user quota, or 3067: // perhaps the entire file system is out of space. 3068: // 3069: // HTTP Mapping: 429 Too Many Requests 3070: RESOURCE_EXHAUSTED = 8; 3071: // The operation was rejected because the system is not in a state 3072: // required for the operation's execution. For example, the directory 3073: // to be deleted is non-empty, an rmdir operation is applied to 3074: // a non-directory, etc. 3075: // 3076: // Service implementors can use the following guidelines to decide 3077: // between `FAILED_PRECONDITION`, `ABORTED`, and `UNAVAILABLE`: 3078: // (a) Use `UNAVAILABLE` if the client can retry just the failing call. 3079: // (b) Use `ABORTED` if the client should retry at a higher level 3080: // (e.g., when a client-specified test-and-set fails, indicating the 3081: // client should restart a read-modify-write sequence). 3082: // (c) Use `FAILED_PRECONDITION` if the client should not retry until 3083: // the system state has been explicitly fixed. E.g., if an "rmdir" 3084: // fails because the directory is non-empty, `FAILED_PRECONDITION` 3085: // should be returned since the client should not retry unless 3086: // the files are deleted from the directory. 3087: // 3088: // HTTP Mapping: 400 Bad Request 3089: FAILED_PRECONDITION = 9; 3090: // The operation was aborted, typically due to a concurrency issue such as 3091: // a sequencer check failure or transaction abort. 3092: // 3093: // See the guidelines above for deciding between `FAILED_PRECONDITION`, 3094: // `ABORTED`, and `UNAVAILABLE`. 3095: // 3096: // HTTP Mapping: 409 Conflict 3097: ABORTED = 10; 3098: // The operation was attempted past the valid range. E.g., seeking or 3099: // reading past end-of-file. 3100: // 3101: // Unlike `INVALID_ARGUMENT`, this error indicates a problem that may 3102: // be fixed if the system state changes. For example, a 32-bit file 3103: // system will generate `INVALID_ARGUMENT` if asked to read at an 3104: // offset that is not in the range [0,2^32-1], but it will generate 3105: // `OUT_OF_RANGE` if asked to read from an offset past the current 3106: // file size. 3107: // 3108: // There is a fair bit of overlap between `FAILED_PRECONDITION` and 3109: // `OUT_OF_RANGE`. We recommend using `OUT_OF_RANGE` (the more specific 3110: // error) when it applies so that callers who are iterating through 3111: // a space can easily look for an `OUT_OF_RANGE` error to detect when 3112: // they are done. 3113: // 3114: // HTTP Mapping: 400 Bad Request 3115: OUT_OF_RANGE = 11; 3116: // The operation is not implemented or is not supported/enabled in this 3117: // service. 3118: // 3119: // HTTP Mapping: 501 Not Implemented 3120: UNIMPLEMENTED = 12; 3121: // Internal errors. This means that some invariants expected by the 3122: // underlying system have been broken. This error code is reserved 3123: // for serious errors. 3124: // 3125: // HTTP Mapping: 500 Internal Server Error 3126: INTERNAL = 13; 3127: // The service is currently unavailable. This is most likely a 3128: // transient condition, which can be corrected by retrying with 3129: // a backoff. Note that it is not always safe to retry 3130: // non-idempotent operations. 3131: // 3132: // See the guidelines above for deciding between `FAILED_PRECONDITION`, 3133: // `ABORTED`, and `UNAVAILABLE`. 3134: // 3135: // HTTP Mapping: 503 Service Unavailable 3136: UNAVAILABLE = 14; 3137: // Unrecoverable data loss or corruption. 3138: // 3139: // HTTP Mapping: 500 Internal Server Error 3140: DATA_LOSS = 15; ... 3766: // Unless required by applicable law or agreed to in writing, software 3767: // distributed under the License is distributed on an "AS IS" BASIS, 3768: // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 3769: // See the License for the specific language governing permissions and 3770: // limitations under the License. 3771: syntax = "proto3"; 3772: package google.rpc; 3773: import "google/protobuf/any.proto"; 3774: import "kurrentdb/protocols/v1/code.proto"; 3775: option cc_enable_arenas = true; 3776: option go_package = "google.golang.org/genproto/googleapis/rpc/status;status"; 3777: option java_multiple_files = true; 3778: option java_outer_classname = "StatusProto"; 3779: option java_package = "com.google.rpc"; 3780: option objc_class_prefix = "RPC"; 3781: // The `Status` type defines a logical error model that is suitable for 3782: // different programming environments, including REST APIs and RPC APIs. It is 3783: // used by [gRPC](https://github.com/grpc). Each `Status` message contains 3784: // three pieces of data: error code, error message, and error details. 3785: // 3786: // You can find out more about this error model and how to work with it in the 3787: // [API Design Guide](https://cloud.google.com/apis/design/errors). 3788: message Status { 3789: // The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. 3790: google.rpc.Code code = 1; 3791: // A developer-facing error message, which should be in English. Any 3792: // user-facing error message should be localized and sent in the 3793: // [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. 3794: string message = 2; 3795: // A list of messages that carry the error details. There is a common set of 3796: // message types for APIs to use. ... 4032: oneof deadline_option { 4033: google.protobuf.Timestamp deadline_21_10_0 = 6; 4034: google.protobuf.Duration deadline = 7; 4035: } 4036: } 4037: message ProposedMessage { 4038: event_store.client.UUID id = 1; 4039: map<string, string> metadata = 2; 4040: bytes custom_metadata = 3; 4041: bytes data = 4; 4042: } 4043: } 4044: message BatchAppendResp { 4045: event_store.client.UUID correlation_id = 1; 4046: oneof result { 4047: google.rpc.Status error = 2; 4048: Success success = 3; ... 4199: } 4200: message ResetPasswordReq { 4201: Options options = 1; 4202: message Options { 4203: string login_name = 1; 4204: string new_password = 2; 4205: } 4206: } 4207: message ResetPasswordResp { 4208: } 4209: // ************************************************************************************** 4210: // This protocol is UNSTABLE in the sense of being subject to change. 4211: // ************************************************************************************** 4212: syntax = "proto3"; 4213: package kurrent.rpc; 4214: option csharp_namespace = "KurrentDB.Protocol.V2.Common.Errors"; 4215: import "kurrentdb/protocols/v2/rpc.proto"; 4216: // The canonical server error codes for the Kurrent Platform gRPC APIs. 4217: // These errors represent common failure modes across all Kurrent services. 4218: enum ServerError { 4219: // Default value. This value is not used. 4220: // An error code MUST always be set to a non-zero value. 4221: // If an error code is not explicitly set, it MUST be treated as 4222: // an internal server error (INTERNAL). 4223: UNSPECIFIED = 0; 4224: // Authentication or authorization failure. 4225: // The client lacks valid credentials or sufficient permissions to perform the requested operation. 4226: // 4227: // Common causes: 4228: // - Missing or invalid authentication tokens 4229: // - Insufficient permissions for the operation 4230: // - Expired credentials 4231: // 4232: // Client action: Check credentials, verify permissions, and re-authenticate if necessary. 4233: // Not retriable without fixing the underlying authorization issue. 4234: SERVER_ERROR_ACCESS_DENIED = 1 [(kurrent.rpc.error) = { 4235: status_code: PERMISSION_DENIED, 4236: has_details: true 4237: }]; 4238: // The request is malformed or contains invalid data. 4239: // The server cannot process the request due to client error. 4240: // 4241: // Common causes: 4242: // - Invalid field values (e.g., empty required fields, out-of-range numbers) 4243: // - Malformed data formats 4244: // - Validation failures 4245: // 4246: // Client action: Fix the request data and retry. 4247: // Not retriable without modifying the request. 4248: SERVER_ERROR_BAD_REQUEST = 2 [(kurrent.rpc.error) = { 4249: status_code: INVALID_ARGUMENT, 4250: has_details: true 4251: }]; 4252: // The server is not the cluster leader and cannot process write operations. 4253: // In a clustered deployment, only the leader node can accept write operations. 4254: // 4255: // Common causes: 4256: // - Client connected to a follower node 4257: // - Leader election in progress 4258: // - Network partition 4259: // 4260: // Client action: Redirect the request to the leader node indicated in the error details. 4261: // Retriable after redirecting to the correct leader node. 4262: SERVER_ERROR_NOT_LEADER_NODE = 5 [(kurrent.rpc.error) = { 4263: status_code: FAILED_PRECONDITION, 4264: has_details: true 4265: }]; 4266: // The operation did not complete within the configured timeout period. 4267: // 4268: // Common causes: 4269: // - Slow disk I/O during writes 4270: // - Cluster consensus delays 4271: // - Network latency 4272: // - Heavy server load 4273: // 4274: // Client action: Retry with exponential backoff. Consider increasing timeout values. 4275: // Retriable - the operation may succeed on retry. 4276: SERVER_ERROR_OPERATION_TIMEOUT = 6 [(kurrent.rpc.error) = { 4277: status_code: DEADLINE_EXCEEDED 4278: }]; 4279: // The server is starting up or shutting down and cannot process requests. 4280: // 4281: // Common causes: 4282: // - Server is initializing (loading indexes, recovering state) 4283: // - Server is performing graceful shutdown 4284: // - Server is performing maintenance operations 4285: // 4286: // Client action: Retry with exponential backoff. Wait for server to become ready. 4287: // Retriable - the server will become available after initialization completes. 4288: SERVER_ERROR_SERVER_NOT_READY = 7 [(kurrent.rpc.error) = { 4289: status_code: UNAVAILABLE 4290: }]; 4291: // The server is temporarily overloaded and cannot accept more requests. 4292: // This is a backpressure mechanism to prevent server overload. 4293: // 4294: // Common causes: 4295: // - Too many concurrent requests 4296: // - Resource exhaustion (CPU, memory, disk I/O) 4297: // - Rate limiting triggered 4298: // 4299: // Client action: Retry with exponential backoff. Reduce request rate. 4300: // Retriable - the server may accept requests after load decreases. 4301: SERVER_ERROR_SERVER_OVERLOADED = 8 [(kurrent.rpc.error) = { 4302: status_code: UNAVAILABLE 4303: }]; 4304: // An internal server error occurred. 4305: // This indicates a bug or unexpected condition in the server. 4306: // 4307: // Common causes: 4308: // - Unhandled exceptions 4309: // - Assertion failures 4310: // - Corrupted internal state 4311: // - Programming errors 4312: // 4313: // Client action: Report to server administrators with request details. 4314: // May be retriable, but likely indicates a server-side issue requiring investigation. 4315: SERVER_ERROR_SERVER_MALFUNCTION = 9 [(kurrent.rpc.error) = { 4316: status_code: INTERNAL 4317: }]; 4318: } 4319: // Details for ACCESS_DENIED errors. 4320: message AccessDeniedErrorDetails { 4321: // The friendly name of the operation that was denied. 4322: string operation = 1; 4323: // The username of the user who was denied access. 4324: optional string username = 2; 4325: // The permission that was required for this operation. 4326: optional string permission = 3; 4327: } 4328: // Details for NOT_LEADER_NODE errors. 4329: message NotLeaderNodeErrorDetails { 4330: // Information about the current cluster leader node. 4331: NodeInfo current_leader = 1; 4332: // Information about a cluster node. 4333: message NodeInfo { 4334: // The hostname or IP address of the node. 4335: string host = 1; 4336: // The gRPC port of the node. 4337: int32 port = 2; 4338: // The unique instance ID of the node. 4339: optional string node_id = 3; 4340: } 4341: } 4342: // ************************************************************************************** 4343: // This protocol is UNSTABLE in the sense of being subject to change. 4344: // **************************************************************************************** 4345: syntax = "proto3"; 4346: package kurrentdb.protocol.v2.registry.errors; 4347: option csharp_namespace = "KurrentDB.Protocol.V2.Registry.Errors"; 4348: import "kurrentdb/protocols/v2/rpc.proto"; 4349: // Error codes specific to the Schema Registry API. 4350: enum RegistryError { 4351: // Default value. This value is not used. 4352: // An error code MUST always be set to a non-zero value. 4353: // If an error code is not explicitly set, it MUST be treated as 4354: // an internal server error (INTERNAL). 4355: REGISTRY_ERROR_UNSPECIFIED = 0; 4356: // // The specified schema could not be found. Please check the schema name and try again. 4357: // REGISTRY_ERROR_NOT_FOUND = 1 [(kurrent.rpc.error) = { 4358: // status_code: NOT_FOUND 4359: // }]; 4360: // 4361: // // The specified schema has already been created and cannot be created again. Please use a different name. 4362: // REGISTRY_ERROR_ALREADY_EXISTS = 2 [(kurrent.rpc.error) = { 4363: // status_code: ALREADY_EXISTS ... 4538: string schema_name = 1; 4539: } 4540: message RegisterSchemaVersionRequest { 4541: string schema_name = 1; 4542: bytes schema_definiti...

…lient-NodeJS into w1am/registry-api

Add schema registry api

353a5b9

w1am force-pushed the w1am/registry-api branch from 1bea053 to 353a5b9 Compare December 18, 2025 12:50

qodo-code-review bot added the Review effort 4/5 label Dec 18, 2025

w1am added 8 commits December 18, 2025 17:07

format service grpc

6d00c1e

Add schema registry to test matrix

0b6eba9

Fix tests

ea22694

Temporarily disable all the other tests

4c02aa1

Format

dc5a58d

Account for eventual consistency

d72f2c5

Merge branch 'w1am/registry-api' of github.com:kurrent-io/KurrentDB-C…

84335ec

…lient-NodeJS into w1am/registry-api

Fix formatting

0e95b51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Schema Registry API #446

Schema Registry API #446

Uh oh!

w1am commented Dec 18, 2025 •

edited by qodo-code-review bot

Loading

Uh oh!

qodo-code-review bot commented Dec 18, 2025 •

edited

Loading

Uh oh!

qodo-code-review bot commented Dec 18, 2025 •

edited

Loading

Examples:

Solution Walkthrough:

Before:

After:

Uh oh!

qodo-code-review bot commented Dec 18, 2025 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Schema Registry API #446

Are you sure you want to change the base?

Schema Registry API #446

Uh oh!

Conversation

w1am commented Dec 18, 2025 • edited by qodo-code-review bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

User description

PR Type

Description

Diagram Walkthrough

File Walkthrough

Uh oh!

qodo-code-review bot commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Compliance Guide 🔍

Uh oh!

qodo-code-review bot commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Code Suggestions ✨

Examples:

Solution Walkthrough:

Before:

After:

Uh oh!

qodo-code-review bot commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CI Feedback 🧐

(Feedback updated until commit 353a5b9)

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

w1am commented Dec 18, 2025 •

edited by qodo-code-review bot

Loading

qodo-code-review bot commented Dec 18, 2025 •

edited

Loading

qodo-code-review bot commented Dec 18, 2025 •

edited

Loading

qodo-code-review bot commented Dec 18, 2025 •

edited

Loading

(Feedback updated until commit `353a5b9`)