docs: add multi-language client specification

[Copilot]

Adds and iteratively improves the multi-language client specification documents for OJP.

Changes Made

• Added Last updated: 2026-04-30 note to CLIENT_SPEC.md and CLIENT_SPEC_AI.md
• Added reference implementation links (classes and methods) for every section in both spec documents
• Updated failover, health-checking, connection redistribution, cluster health propagation, and error mapping sections to reflect recent server fixes (PRs Optimize connect() RPCs: skip for non-XA repeat connections, single-server for XA #442–fix: preserve healthy-server count across pool creation races in multinode setup #449)
• Rewrote §2 as "Connection Configuration and Building ConnectionDetails" to be language-agnostic (removed JDBC URL parsing)
• Added pseudo-code gRPC examples to every section that interacts with the OJP server
• Restructured CLIENT_SPEC.md for readability: Overview, Core Concepts, Architecture Flow, Client Responsibilities, Lifecycle Walkthrough, Error Handling, Minimal Example, Implementation Guidance
• Created machine-oriented CLIENT_SPEC_AI.md with RFC-style keywords, state machine, protocol model, concurrency model, error/retry semantics, session affinity rules, versioning, compliance requirements, and action→protocol mapping
• Replaced all HikariCP-specific pool references with pool-agnostic wording (SPI extensibility noted)
• Added language equivalents table to §1 Overview of CLIENT_SPEC.md mapping Go, Python, C#/.NET, C++, Node.js, Ruby, PHP, and Dart to their respective standard database-access APIs

[rrobetti]

Now I want you to link where in the OJP JDBC driver each of these parts are implemented exactly, you don't need to copy code just point to the most relevant classes and methods.

[Copilot]

Now I want you to link where in the OJP JDBC driver each of these parts are implemented exactly, you don't need to copy code just point to the most relevant classes and methods.

Done in d86de06. Every section (§1–§26) now has a > Reference implementation: block at its end that points to the most relevant classes and methods in the driver. For example:

• §1 gRPC Interface → StatementService interface, StatementServiceGrpcClient (all RPC stubs), MultinodeStatementService (multinode façade), GrpcChannelFactory
• §2 URL Parsing → MultinodeUrlParser.parseServerEndpoints(), extractActualJdbcUrl(), replaceBracketsWithSingleEndpoint(), UrlParser.parseUrlWithDataSource(), Driver.connect()
• §3 Client Identity → ClientUUID.getUUID()
• §4 connHash Caching → MultinodeConnectionManager.connect(), buildLocalSessionInfo(), computeConnectionKey(), invalidateConnHash(), reconnectForConnHash()
• §7 Load Balancing → selectByLeastConnections(), selectByRoundRobin(), ServerEndpoint
• §16 Parameter Mapping → ProtoConverter.toProto/fromProto/toParameterValue/fromParameterValue, ProtoTypeConverters, BigDecimalWire
• §17 Temporal Types → all methods in TemporalConverter
• §26 Testing → a full table mapping each test area to its Java test class(es) (BasicCrudIntegrationTest, MultinodeFailoverTest, ConnectRpcSkipOptimisationTest, etc.)

Links use relative paths from the spec file to the source files in the repo.

[rrobetti]

@copilot there were some recent PR, yesterday and today to fix the way we recognize that an ojp server is down and to rebalance pools, review if that impacts the documentation of this specification

[Copilot]

@copilot there were some recent PR, yesterday and today to fix the way we recognize that an ojp server is down and to rebalance pools, review if that impacts the documentation of this specification

Reviewed PRs #442–#449. Five spec sections were out of date — updated in bd1c1bd:

§8 Failover

• Error table: added CANCELLED row ("do not failover; do not mark unhealthy"). Before PR Fix SQL exception propagation: server used wrong gRPC status code for SQL errors #444 the server incorrectly sent SQL errors as CANCELLED; that bug is fixed, but any implementation must guard against it.
• Failover procedure: step 1 now documents that handleServerFailure() (a) captures wasHealthy before acting, (b) shuts down the gRPC channel gracefully, and (c) submits pushClusterHealthToAllHealthyServers() to the background scheduler asynchronously so query threads are never blocked (PR Fix flaky multinode pool expansion after server failure detected by query thread #447).

§9 Health Checking

• Phase 1 guard updated: the periodic check now fires when there are active XA sessions or cached non-XA connection details (!sessionToServerMap.isEmpty() || !connectionDetailsByConnHash.isEmpty()). The old guard (sessionToServerMap only) was a bug that prevented non-XA workloads from ever detecting a down server proactively (PR fix(multinode): proactively reinitialize pool on recovered server for non-XA connections #443).

§10 Connection Redistribution

• Recovery procedure: made the strict ordering explicit — reinitializePoolOnRecoveredServer() must run before endpoint.markHealthy() to eliminate the NOT_FOUND window (PR fix(multinode): eliminate NOT_FOUND window on server recovery for non-XA connections #445). Also documented the guard: reinitialize only runs when !connectionDetailsByConnHash.isEmpty() (was previously dead code due to an inverted guard, PR fix(multinode): proactively reinitialize pool on recovered server for non-XA connections #443).

§11 Cluster Health Propagation

• "Push" responsibility now documents both independent triggers: Trigger 1 (health-check thread, inline) and Trigger 2 (query thread, submitted to background scheduler). Both are required — removing either breaks one failure-detection scenario (PR Fix multinode pool resize race: proactive cluster health push on topology change #446, Fix flaky multinode pool expansion after server failure detected by query thread #447).

§21 Error Mapping

• Added CANCELLED row to the classification table and a note about the historical CANCELLED-as-SQL-error bug (PR Fix SQL exception propagation: server used wrong gRPC status code for SQL errors #444).

[rrobetti]

@copilot here you need to remember that in other languages the connection URL will probably not be the JDBC url, so focus on how to assamble the connection details to send to server, not how to parse JDBC URL, remove how to parse JDBC URL.

[Copilot]

Done in 35ae38f. §2 has been completely rewritten as "Connection Configuration and Building ConnectionDetails". The JDBC URL format and parsing rules are gone. The section now:

• Lists the four pieces of configuration a non-Java client collects from the user (OJP server endpoints, datasource name, actual database URL, credentials, optional properties)
• Maps each to the corresponding ConnectionDetails proto field in a table
• Documents the server-side connHash computation (SHA-256 of url + user + password + datasource_name) and the client-side cache key formula so implementors know what must be consistent across clients
• Keeps a reference to MultinodeUrlParser solely as a Java-specific note at the end of the reference block, making clear it is not needed in non-Java clients

[rrobetti]

@copilot I want you to enrish each part that interacts with OJP server with a pseudo code example of how to create the grpc request and what is expected in the response. This should be for guiding purposes, not verbose, it does not to be fully acurate but it does have to be clear and easy to understand by a mid level developer.

[Copilot]

@copilot I want you to enrish each part that interacts with OJP server with a pseudo code example of how to create the grpc request and what is expected in the response. This should be for guiding pur...

Done in 11300c6. Every section that calls a gRPC RPC now has a ### Pseudo-code block showing how to build the request and what to expect in the response. The examples use readable Python-like pseudocode, are non-verbose, and focus entirely on the gRPC interface:

• §1 — channel creation and graceful shutdown
• §4 — connect() RPC (first connect, cache-hit path, and NOT_FOUND recovery)
• §5 — session propagation pattern (resp.session update) and terminateSession()
• §9 — lightweight heartbeat probe and full-validation probe
• §11 — build_cluster_health(), push_cluster_health() via connect(), and consume_cluster_health() from responses
• §12 — startTransaction(), commitTransaction(), rollbackTransaction(), and isolation level via callResource()
• §13 — savepoint create (CALL_SET), rollback (CALL_ROLLBACK), and release (CALL_RELEASE) via callResource()
• §14 — full XA lifecycle: xaStart → xaEnd → xaPrepare → xaCommit/xaRollback, plus xaRecover and xaForget
• §15 — executeUpdate() with parameters, executeQuery() streaming iteration, and stored procedure via CALL_PREPARE/CALL_EXECUTE
• §18 — fetchNextRows() pagination loop and cursor navigation via callResource(CALL_ABSOLUTE, ...)
• §19 — createLob() client-streaming chunks and readLob() server-streaming reassembly
• §20 — generic callResource() examples: get metadata, check capability, cancel statement, and chained call

Also reframed two JDBC-centric sections: §12 now describes the transaction lifecycle in terms of the three RPCs (not autoCommit), and §15 now describes SQL execution in terms of parameterless SQL / parameterized SQL / stored-procedure calls (not Plain/Prepared/Callable Statement).

[rrobetti]

You are working on the following file:

documents/multi-language-client-spec/CLIENT_SPEC.md

Your task has TWO parts:

PART 1 — Improve the EXISTING document (for human readers)

Refactor the current document in place to make it clearer, easier to read, and more useful for developers implementing a client.

Goals
Improve readability and flow
Reduce ambiguity
Make concepts easier to understand
Keep all existing technical meaning intact
Rules
DO NOT remove important technical content
DO NOT introduce new features or behavior
DO NOT change the intent of the specification
You MAY reorganize, rewrite, and clarify
Prefer clear paragraphs over excessive bullet points
Avoid overly dense sections
Required Changes

1. Restructure the document

Reorganize the content into this structure:

Overview
Core Concepts
Architecture Flow
Client Responsibilities
Lifecycle Walkthrough
Error Handling (high-level)
Minimal Example (pseudo-code)
Implementation Guidance
2. Clarify key concepts

Make these concepts explicitly explained in simple terms:

Virtual connections
Deferred execution (real DB connection only on execution)
Session affinity
Client vs server responsibilities
3. Improve flow
Ensure sections follow a logical progression
Avoid jumping between abstraction levels
Add short transitions between sections where needed
4. Add a simple end-to-end example

Include a language-neutral pseudo-code example:

connect
prepare
execute
close

Keep it simple and readable

5. Reduce ambiguity

Where behavior is unclear:

Rewrite to be more explicit
Avoid vague wording like “may”, “typically”, “usually” unless intentional
6. Keep it developer-friendly
Write as if explaining to an experienced engineer new to OJP
Avoid protocol-level deep detail (this will go in the AI spec)
PART 2 — Create a NEW AI-oriented specification

Create a NEW file:

documents/multi-language-client-spec/CLIENT_SPEC_AI.md

This document must be machine-oriented and unambiguous, suitable for code generation tools.

Requirements for the new file
Use strict, formal language
Use RFC-style keywords:
MUST
MUST NOT
SHOULD
MAY
Avoid narrative explanations
Prefer structured definitions
Structure of CLIENT_SPEC_AI.md

1. Terminology

Define all important terms precisely

2. State Machine (MANDATORY)

Define:

All states
All transitions
Invalid transitions and expected behavior
3. Protocol Model

Define request/response structures in a language-agnostic way:

Example:

ExecuteRequest:

connectionId: string
sql: string
parameters: list
options: map
4. Client Contract

Define:

When connections are created
When real DB connections are acquired
Execution behavior rules
5. Concurrency Model

Define:

Thread safety expectations
Whether concurrent execution is allowed
Ordering guarantees
6. Error Handling & Retry Semantics

Define:

Retry rules
Timeout behavior
Connection invalidation
7. Session & Affinity Rules

Define:

When affinity is required
How it is maintained
8. Versioning & Compatibility

Define:

Version handling expectations
Backward compatibility rules
9. Compliance Requirements

Define what a valid client MUST implement

10. Action → Protocol Mapping

Map high-level operations to protocol calls:

Example:

connect() → CreateConnectionRequest
prepare(sql) → PrepareStatementRequest
execute() → ExecuteRequest

Final Notes
Ensure both documents are consistent with each other
The human document explains concepts clearly
The AI document defines exact behavior with no ambiguity
Do not duplicate unnecessary text between the two files

[rrobetti]

Avoid termso like "in the server's HikariCP pool", OJP supports other pools via SPI.

[Copilot]

Avoid termso like "in the server's HikariCP pool", OJP supports other pools via SPI.

Fixed in 045e484. All four pool-specific "HikariCP pool" phrases in CLIENT_SPEC.md and CLIENT_SPEC_AI.md have been replaced with pool-agnostic wording. The only remaining mention is a parenthetical in the overview — "(HikariCP by default, replaceable via SPI)" — which accurately describes the default while making the SPI extensibility explicit.

[rrobetti]

Check if latest commits require update on these docs in these PRs. Just double check, I don't believe they do.

[Copilot]

Check if latest commits require update on these docs in these PRs. Just double check, I don't believe they do.

Reviewed all commits merged to main since the last spec update (April 20). No changes to CLIENT_SPEC.md or CLIENT_SPEC_AI.md are needed:

• 28bd808 — Connection.callProxy SQLException propagation fix: internal client bug, no protocol change
• 45a3615 — Oracle/DB2 savepoint test corrections: test-only, spec already notes database-specific savepoint limitations
• 1690f55 — H2 transaction integration test added: new test, §8 already covers transaction testing
• 796de61 — Micronaut OjpDataSource docs: Java framework docs, out of scope for the multi-language spec
• 4b8aa36 — Action Pattern (ADR-009): server-side internal dispatch; client spec already correctly documents callResource as the client-visible API
• Security/CI commits: no relevance to spec

The docs are current.

[rrobetti]

@copilot add this information.

Language	JDBC Equivalent / Standard API	Description
Go	database/sql	The standard Go package providing a generic interface for SQL-like databases.
Python	DB-API 2.0 (pep-249)	A standard specification followed by almost all Python database drivers (e.g., psycopg2, sqlite3).
C# / .NET	ADO.NET	The foundational data access technology for .NET, using standard classes like DbConnection.
C++	ODBC	The "Open Database Connectivity" standard used for cross-platform database-agnostic apps.
Node.js	Common Driver Patterns / ORMs	Relies on community standards or ORMs like Sequelize or Prisma rather than a single built-in API.
Ruby	DBI / Active Record	Uses the Database Interface (DBI) module or the Active Record abstraction layer.
PHP	PDO (PHP Data Objects)	A lightweight, consistent interface for accessing various databases in PHP.
Dart	sql_conn / drift	Uses specific community packages or the Drift library for structured data access.

[Copilot]

@copilot add this information.

...

Added in facf718. The table is placed in §1 Overview under a new "Language Equivalents" subsection, right before the operational rule, so readers immediately understand what each language's native API maps to before diving into implementation details.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud