Immutable HttpHeaders and Cookies

HttpHeaders in Armeria is mutable. Although it is convenient to use, it sometimes leads us to a surprising behavior when it’s modified by an unexpected place.

To address such issues, I’d like to propose to make HttpHeaders immutable, which means modifying an HttpHeaders will result in a new HttpHeaders instance. The following is an example of the API I have in mind:

// Mutable headers. Behaves like current HttpHeaders do.
MutableHeaders mh1 = MutableHeaders.of().add("name", "value");

// Immutable headers. Does not have methods like 'set()'.
Headers ih1 = ImmutableHeaders.of("name", "value", ...);

// Conversion to immutable headers.
Headers ih2 = mh1.toImmutable();

// Conversion to mutable headers.
MutableHeaders mh2 = ih2.toMutable();
assertThat(mh2).isEqualTo(mh1);
assertThat(mh2).isNotSameAs(mh1); 

// Mutation of immutable headers.
Headers ih3 = ih2.mutate((MutableHeaders h) -> {
    h.set("name", "new-value");
    ...
});

// One-time mutation.
Headers ih4 = ih2.mutator().set("name", "new-value");

Thoughts? I’d like to get as much feed back (e.g. what could be a problem when we do this?) as possible because this will be a big breaking change. To be honest, I may even fail to refactor Armeria itself because Armeria itself relies on mutability of HttpHeaders in some places.

Note that I removed Http from the type names, which may need an additional discussion as well.

[trustin]

This is a rough preview of the new API:

• HeaderGetters - provides the getters to Headers and HeadersBuilder
  • HeaderGetters.java
  • RequestHeaderGetters.java
  • ResponseHeaderGetters.java
• Headers - immutable HTTP/2 headers
  • Headers.java
  • RequestHeaders.java
  • ResponseHeaders.java
• HeadersBuilder - builds a Headers
  • HeadersBuilder
  • RequestHeadersBuilder
  • ResponseHeadersBuilder

Note that Headers now have two new subtypes RequestHeaders and ResponseHeaders. They are essentially same, but they are different in which shortcut methods they expose. It was inspired by @anuraaga’s suggestion about separating AggregatedHttpMessage into AggregatedHttpRequest and AggregatedHttpResponse.

The following is the example usage:

RequestHeaders h = RequestHeaders.of(HttpMethod.GET, "/foo");
RequestHeaders h = RequestHeaders.of(HttpMethod.GET, "/foo",
                                     HttpHeaderNames.ACCEPT_ENCODING, "gzip",
                                     HttpHeaderNames.AUTHORITY, "foo.com");
RequestHeaders h = new RequestHeadersBuilder(HttpMethod.GET, "/foo")
    .add(HttpHeaderNames.ACCEPT_ENCODING, "gzip")
    .add(HttpHeaderNames.AUTHORITY, "foo.com")
    .build();

RequestHeaders h = h.toBuilder()
                    .add(HttpHeaderNames.USER_AGENT, "baz")
                    .build();

RequestHeaders h = h.mutate(mutator -> {
    mutator.add(HttpHeaderNames.USER_AGENT, "baz");
    mutator.remove(HttpHeaderNames.ACCEPT_ENCODING);
});

[southernkasaist]

How about using builder way like guava immutable types (ImmutableList.Builder, etc)? e.g.,

Headers headers = ImmutableHeaders.builder().add("name1", "value1").build();
Headers other = headers.toBuilder().add("name2", "value2").set("name1", "value3").build();