adutra commented on code in PR #17727:
URL: https://github.com/apache/iceberg/pull/17727#discussion_r4095317576
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -2185,51 +2190,54 @@ components:
name: User-Agent
in: header
description: >
- Recommended header for a client to identify itself to the catalog. It
- follows the standard HTTP `User-Agent` grammar (RFC 7231, Section
- 5.5.3): a whitespace-separated list of `product/version` tokens,
- optionally followed by a parenthesized comment.
-
-
- Tokens SHOULD be ordered from the outermost component to the innermost,
+ Header for a client to identify itself to the catalog. It follows the
+ standard HTTP `User-Agent` grammar (RFC 7231, Section 5.5.3): a
+ whitespace-separated list of `product/version` tokens, optionally
+ followed by a parenthesized comment.
+
+
+ Clients SHOULD send this header. When it is sent, the Iceberg client
+ library token MUST be present so that a server can always identify the
+ library and its version: use `iceberg-java`, `pyiceberg`,
+ `iceberg-rust`, or `iceberg-go`. A client not built on an Iceberg
+ library uses its own product token in that position. The remaining
+ tokens SHOULD be ordered from the outermost component to the innermost,
so the most specific caller appears first: the engine or application,
- then any integration or connector, then the Iceberg client library,
- then the language runtime. The Iceberg client library token is the one
- component every client can supply and SHOULD always be present.
- Recommended library tokens are `iceberg-java`, `pyiceberg`,
- `iceberg-rust`, and `iceberg-go`.
+ then any integration or connector, then the Iceberg library, then the
+ language runtime.
Review Comment:
Language runtime is mentioned twice: here as a product token, then below
(line 2212) as a comment. I think the final intent is to move language runtime
info to comments.
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -2185,51 +2190,54 @@ components:
name: User-Agent
in: header
description: >
- Recommended header for a client to identify itself to the catalog. It
- follows the standard HTTP `User-Agent` grammar (RFC 7231, Section
- 5.5.3): a whitespace-separated list of `product/version` tokens,
- optionally followed by a parenthesized comment.
-
-
- Tokens SHOULD be ordered from the outermost component to the innermost,
+ Header for a client to identify itself to the catalog. It follows the
+ standard HTTP `User-Agent` grammar (RFC 7231, Section 5.5.3): a
+ whitespace-separated list of `product/version` tokens, optionally
+ followed by a parenthesized comment.
+
+
+ Clients SHOULD send this header. When it is sent, the Iceberg client
+ library token MUST be present so that a server can always identify the
+ library and its version: use `iceberg-java`, `pyiceberg`,
+ `iceberg-rust`, or `iceberg-go`. A client not built on an Iceberg
+ library uses its own product token in that position. The remaining
+ tokens SHOULD be ordered from the outermost component to the innermost,
so the most specific caller appears first: the engine or application,
- then any integration or connector, then the Iceberg client library,
- then the language runtime. The Iceberg client library token is the one
- component every client can supply and SHOULD always be present.
- Recommended library tokens are `iceberg-java`, `pyiceberg`,
- `iceberg-rust`, and `iceberg-go`.
+ then any integration or connector, then the Iceberg library, then the
+ language runtime.
- The trailing parenthesized comment is an open extension point for
- additional, lower-value context such as build identifiers, the HTTP
- library, or the operating system, given as bare tokens or `key=value`
- pairs separated by `; `. Servers SHOULD treat the comment as free-form
- and MUST NOT depend on its contents.
+ The optional trailing comment, enclosed in parentheses as defined by
+ the RFC, carries lower-value context such as build identifiers, the
+ HTTP library, the language runtime, or the operating system. Everything
Review Comment:
It would be good to clarify:
1. whether all of these items should appear in different comments, or
together in a single one, or both? E.g.
```
(apache-http 5.0; jvm 17.0.9; ubuntu 26.04)
(apache-http 5.0) (jvm 17.0.9) (ubuntu 26.04)
```
2. whether comments can appear interleaved with products, or only at the end
after the products.
The RFC allows all of the above, but maybe we could restrict the expected
format to facilitate parsing.
##########
open-api/rest-catalog-open-api.yaml:
##########
@@ -2185,51 +2190,54 @@ components:
name: User-Agent
in: header
description: >
- Recommended header for a client to identify itself to the catalog. It
- follows the standard HTTP `User-Agent` grammar (RFC 7231, Section
- 5.5.3): a whitespace-separated list of `product/version` tokens,
- optionally followed by a parenthesized comment.
-
-
- Tokens SHOULD be ordered from the outermost component to the innermost,
+ Header for a client to identify itself to the catalog. It follows the
+ standard HTTP `User-Agent` grammar (RFC 7231, Section 5.5.3): a
+ whitespace-separated list of `product/version` tokens, optionally
+ followed by a parenthesized comment.
+
+
+ Clients SHOULD send this header. When it is sent, the Iceberg client
+ library token MUST be present so that a server can always identify the
+ library and its version: use `iceberg-java`, `pyiceberg`,
+ `iceberg-rust`, or `iceberg-go`. A client not built on an Iceberg
Review Comment:
How about `iceberg-cpp`?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
