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.

Sign up for GitHub

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

Document HTTP/2 support #330

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
35d1a3a
Document HTTP/2 support
reta Jan 16, 2023
b51e40e
Addressing code review comments
reta Jan 17, 2023
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
View file
Open in desktop
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
24 changes: 21 additions & 3 deletions USER_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,28 +56,46 @@ There are multiple low level transports which `OpenSearchClient` could be config
### Create a client using `RestClientTransport`

```java
Transport transport = new RestClientTransport(restClient, new JacksonJsonpMapper());
OpenSearchTransport transport = new RestClientTransport(restClient, new JacksonJsonpMapper());
Copy link
Collaborator Author

@reta reta Jan 17, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

Just noticed that OpenSearchClient does not accept Transport but OpenSearchTransport, fixed that in the guide

OpenSearchClient client = new OpenSearchClient(transport);
```

The `JacksonJsonpMapper` class (2.x versions) only supports Java 7 objects by default. [Java 8 modules](https://github.com/FasterXML/jackson-modules-java8) to support JDK8 classes such as the Date and Time API (JSR-310), `Optional`, and more can be used by including [the additional datatype dependency](https://github.com/FasterXML/jackson-modules-java8#usage) and adding the module. For example, to include JSR-310 classes:

```java
Transport transport = new RestClientTransport(restClient,
OpenSearchTransport transport = new RestClientTransport(restClient,
new JacksonJsonpMapper(new ObjectMapper().registerModule(new JavaTimeModule())));
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 •
edited
Loading

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
final Transport transport = ApacheHttpClient5TransportBuilder
final OpenSearchTransport transport = ApacheHttpClient5TransportBuilder
.builder(hosts)
.mapper(new JacksonJsonpMapper())
.build();
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`, for example:

```java
final OpenSearchTransport transport = ApacheHttpClient5TransportBuilder
.builder(httpHost)
.setMapper(new JacksonJsonpMapper())
.setHttpClientConfigCallback(new ApacheHttpClient5TransportBuilder.HttpClientConfigCallback() {
@Override
public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) {
return httpClientBuilder.setVersionPolicy(HttpVersionPolicy.FORCE_HTTP_2);
}
})
.build();
OpenSearchClient client = new OpenSearchClient(transport);
```

## Create an index

```java
Expand Down
Loading