Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document HTTP/2 support #330

Merged
merged 2 commits into from
Jan 18, 2023
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
- Add 1-click release workflows ([#321](https://github.com/opensearch-project/opensearch-java/pull/321))
- Introduce new OpenSearchTransport based on Apache HttpClient 5 ([#281](https://github.com/opensearch-project/opensearch-java/pull/281))
- Add workflow to publish snapshots via GHA ([#325](https://github.com/opensearch-project/opensearch-java/pull/325))
- Document HTTP/2 support ([#330](https://github.com/opensearch-project/opensearch-java/pull/330))

### Dependencies
- Bumps `classgraph` from 4.8.149 to 4.8.154
Expand Down
4 changes: 4 additions & 0 deletions USER_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,8 @@ Transport transport = new RestClientTransport(restClient,
OpenSearchClient client = new OpenSearchClient(transport);
```

Upcoming OpenSearch `3.0.0` release brings HTTP/2 support and as such, the `RestClientTransport` would switch to HTTP/2 if available (for both HTTPS and/or HTTP protocols). The desired protocol could be forced using `RestClientBuilder.HttpClientConfigCallback`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How can I see what protocol has been chosen?
Example of how I would switch to/from HTTP/2?

Copy link
Collaborator Author

@reta reta Jan 17, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How can I see what protocol has been chosen?

Basically this could be done by:

  • inspecting the traffic
  • logging requests and responses (they contain HTTP protocol version)

I am not sure what kind of prove we could provide here.

Example of how I would switch to/from HTTP/2?

RestClientBuilder.HttpClientConfigCallback should be documented in core but I will add the configuration snippet for Apache HttpClient 5 transport.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For documentation generally I ask myself "what would I do". So if you think logging is how you'd do it, I'd show here (or somewhere in the docs) how to log the HTTP version chosen.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For documentation generally I ask myself "what would I do". So if you think logging is how you'd do it, I'd show here (or somewhere in the docs) how to log the HTTP version chosen.

This is not something we should be worried about here (I think), there are few things involved on our behalf:

  • for HTTPS, we have the ALPN protocol in place
  • for HTTP, we have Upgrade in place

The OpenSearch Java client could connect to 2.x clusters fe, that would mean using HTTP/1.1 no matter what. Generally, forcing the protocol is the only reliable way (I am aware of) to make sure only HTTP/1.1 or only HTTP/2 has to be used.

To this point, we would be building features on top of HTTP/2 very soon (I believe), so the presence of HTTP/2 would be obvious.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair enough.


### Create a client using `ApacheHttpClient5Transport`

```java
Expand All @@ -78,6 +80,8 @@ final Transport transport = ApacheHttpClient5TransportBuilder
OpenSearchClient client = new OpenSearchClient(transport);
```

Upcoming OpenSearch `3.0.0` release brings HTTP/2 support and as such, the `ApacheHttpClient5Transport` would switch to HTTP/2 if available (for both HTTPS and/or HTTP protocols). The desired protocol could be forced using `ApacheHttpClient5TransportBuilder.HttpClientConfigCallback`.

## Create an index

```java
Expand Down