Repository navigation
[client-v2] Send the User-Agent in the standard client format and add client metadata - #3213
Open
polyglotAI-bot wants to merge 2 commits into
Open
polyglotAI-bot wants to merge 2 commits into
polyglotAI-bot wants to merge 2 commits into
Conversation
… client metadata The User-Agent header is now '<client name> clickhouse-java-v2/<version> (<key>:<value>; ...; lv:java/<java.version>; os:<os.name>)', the format that clickhouse-go, clickhouse-js, clickhouse-connect and clickhouse-rs use. 'jvm:' becomes 'lv:java/', the OS becomes the 'os:' entry, and the trailing 'Apache-HttpClient/<version>' token is removed. Client.Builder#setClientMetadata(Map) (property 'client_metadata', 'key1=value1,key2=value2') adds key/value pairs to the comment group, before 'lv' and 'os'. Entries that would break the format are rejected with ClientMisconfigurationException when the client is built. Implements: #3202 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 task
Client V2 CoverageCoverage Report
Class Coverage
|
JDBC V2 CoverageCoverage Report
Class Coverage
|
JDBC V1 CoverageCoverage Report
Class Coverage
|
Client V1 CoverageCoverage Report
Class Coverage
|
Open
1 task
chernser
requested changes
Oct 16, 2026
chernser
left a comment
chernser
left a comment
Contributor
There was a problem hiding this comment.
- move client identification logic into WorkloadIdentitySupport class.
- make it around
User-Agentheader so future transport implementations do not skip this feature - add another method com.clickhouse.client.api.Client.Builder#setClientName with metadata options
- User still should specify set client name instead of setting User-Agent header - this should be stated in the documentation.
Address review feedback on #3213: - Add WorkloadIdentitySupport. It builds the User-Agent value (client name or custom User-Agent, then clickhouse-java-v2/<version> with the metadata, lv and os entries) and validates client metadata entries. HttpAPIClientHelper only reads a custom User-Agent header and sets the value that the class returns. - Replace Client.Builder#setClientMetadata(Map) with Client.Builder#setClientName(String, Map). setClientName(String) does not change the metadata. The client_metadata property is unchanged. - State in the docs and in the httpHeader Javadoc that applications set the client name, not the User-Agent header. Implements: #3202 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Collaborator
Author
|
@chernser Thank you for the review. I pushed aabc06e:
Not changed: jdbc-v2 still builds its own application part ( Tests (ClickHouse 26.9): client-v2 unit 760/760, jdbc-v2 unit 1963/1963, client-v2 User-Agent integration tests 11/11, jdbc-v2 User-Agent integration tests 6/6, |
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements #3202. client-v2 now sends the
User-Agentheader in the standard ClickHouse client format, which clickhouse-go, clickhouse-js, clickhouse-connect and clickhouse-rs already use:jvm:<version>is nowlv:java/<version>. The OS is now theos:entry.Apache-HttpClient/<version>token is removed. The issue allows "drop it or move it into a key". The expected string in the issue drops it, and none of the sibling clients reports its HTTP library, so this PR drops it.Client.Builder#setClientName(String, Map<String, String>)sets the client name and adds key/value pairs to the comment group, beforelvandos.WorkloadIdentitySupport. It builds the completeUser-Agentvalue, so a transport only sets the header.Example from the issue:
Closes #3202
Design
WorkloadIdentitySupport(client-v2/.../api/internal) owns the client identification.getUserAgent(customUserAgent, requestConfig)returns the completeUser-Agentvalue: the application part (a customUser-Agentheader if one is set, else the client name; blank counts as not set), thenclickhouse-java-v2/<version> (<metadata>; lv:...; os:...). It also validates metadata entries.HttpAPIClientHelperonly reads the custom header and sets the returned value, so a new transport gets the same identification from the same class.Config property
client_metadata(ClientConfigProperties.CLIENT_METADATA,Map.class, appended at the end of the enum). It follows the existingtype_hint_mappingpattern: string formkey1=value1,key2=value2, parsed bytoKeyValuePairsinto an ordered map. Because it is a property, JDBC gets it through connection properties and URL parameters without jdbc-v2 code changes.Builder method
setClientName(String, Map)(an overload ofsetClientName) writes the client name and that string form.setClientName(String)does not change the metadata (jdbc-v2 calls it after it applies the connection properties). Escaping is handled by the new package-privateClientConfigProperties.fromKeyValuePairs(inverse oftoKeyValuePairs). Entries keep the iteration order of the map.nullor an empty map removes the setting.Validation is called from
CLIENT_METADATA.parseValue(rules inWorkloadIdentitySupport.checkClientMetadataEntry), so it covers the builder,setOptionand JDBC. It is the same pattern asssl_cipher_suites.build()throwsClientMisconfigurationExceptionif::;(),=;;();lvoros(reserved).These rules keep the comment group parseable. Keys and values are trimmed, and entries with an empty key or value are ignored.
Client-level only. The metadata is put into the cached default User-Agent when the client is created. It is kept when
Client#updateClientName/ JDBCsetClientInfo(ApplicationName)changes the application part, and when a customUser-Agentheader is set. It is not read from operation settings. This is documented, and a test covers it.The application part is unchanged: a custom
User-Agentheader, else the client name. The docs and thehttpHeaderJavadoc state that applications must set the client name, not theUser-Agentheader.Compatibility
This intentionally changes the HTTP
User-Agentoutput (a high-risk surface perdocs/ai-review.md). The change is requested in #3202.system.query_log.http_user_agentforjvm:orApache-HttpClient/must use the new format.setClientName(String, Map), and the internal classWorkloadIdentitySupport.apache.http.client.versionkey fromclient-v2-version.properties. Only the removed User-Agent code read it.Not changed: jdbc-v2 still adds detected frameworks as its own group after
jdbc-v2/<version>(e.g.((apache.spark)), with double parentheses). That is a separate issue. Moving frameworks intoclient_metadatawould change jdbc-v2 output and needs a key name, so it is left for a follow-up.Changes
WorkloadIdentitySupport(new, internal): builds theUser-Agentvalue in the standard format plus metadata, and validates metadata entries.ClientConfigProperties:CLIENT_METADATA;fromKeyValuePairshelper.Client.Builder#setClientName(String, Map);setClientName(String)andhttpHeaderJavadoc state to use the client name, not theUser-Agentheader. Same note onCommonSettings#httpHeader.HttpAPIClientHelper: delegates toWorkloadIdentitySupport. Removed the Apache HttpClient version lookup.docs/features.md(client-v2 entry, jdbc-v2 client-info bullet),docs/clickhouse-docs/client.mdx(builder table, Client Identification),docs/clickhouse-docs/jdbc.mdx,docs/integration-client.md,docs/integration-jdbc.md.history/latest/3202.md.Test
UserAgentUnitTest(new, WireMock): asserts the exact header on the wire throughClient#query. Rows: no name; the issue example;setOptionstring form; escaped,/=/\in a value; empty value ignored; empty and blank client name with metadata;setOptionmetadata kept bysetClientName(String)and replaced bysetClientName(String, Map);setClientName(String)keeps metadata; metadata cleared withnulland with an empty map; customUser-Agentheader plus metadata. A second test coversupdateClientName, an operation-levelUser-Agentheader, and operation-levelclient_metadata(ignored). A third test checks that invalid metadata is rejected atbuild().ClientConfigPropertiesTest: valid parse rows (order, trim, empty entries,:and=in values). Invalid rows: each forbidden character, control and non-ASCII characters, reserved keys, stray,/ tokens without=. Also anullrow and a round trip offromKeyValuePairs.HttpTransportTests#testUserAgentHasCompleteProductName: the data-provider patterns asserted the old format, so they now assert the new format withlv:andos:. This is the only existing test whose expectations changed.ConnectionTest#testClientMetadataInUserAgent(new, jdbc-v2 integration):client_metadataas a connection property and as a URL parameter, checked insystem.query_log, also aftersetClientInfo(ApplicationName).executeQueryAndVerifyUserAgentnow also returns the user agent. Its assertions did not change.os:makes 5UserAgentUnitTestrows fail.Run locally (ClickHouse 26.9, head
aabc06e75): client-v2 unit 760/760; jdbc-v2 unit 1963/1963; client-v2HttpTransportTestsUser-Agent/client-name integration tests 11/11; jdbc-v2ConnectionTestUser-Agent tests 6/6;packages/clickhouse-jdbc-allpackages.docs/changes_checklist.mdclient_metadatais unique and has no default. Its value typeMapmatchesparseValue.ClientMisconfigurationException). It does not overlap an existing property.docs/features.mdis updated.setClientName(String, Map)is an overload ofsetClientNameand follows thetypeHintMappingbuilder pattern for the map. Nullability is documented. Behavior tests are added.system.query_logfor client-v2 and jdbc-v2).warn/ onedebugfor the HTTP client version lookup.Checklist
history/latest/3202.md)docs/features.md,docs/clickhouse-docs/*.mdx, integration guides)Pre-PR validation gate
system.query_log)setOption, JDBC property and URL, runtime client-name changes, custom header at client and operation levelAGENTS.md,docs/ai-review.md,docs/changes_checklist.md🤖 Generated with Claude Code