io.servicetalk.http.netty.H2ProtocolConfig Maven / Gradle / Ivy
Show all versions of servicetalk-http-netty Show documentation
/*
* Copyright © 2019 Apple Inc. and the ServiceTalk project authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package io.servicetalk.http.netty;
import io.servicetalk.http.api.Http2Settings;
import io.servicetalk.http.api.HttpProtocolConfig;
import io.servicetalk.logging.api.UserDataLoggerConfig;
import java.time.Duration;
import java.util.function.BiPredicate;
import javax.annotation.Nullable;
/**
* Configuration for HTTP/2 protocol.
*
* @see HttpProtocolConfigs#h2Default()
*/
public interface H2ProtocolConfig extends HttpProtocolConfig {
@Override
default String alpnId() {
return AlpnIds.HTTP_2;
}
/**
* Sensitivity detector to determine if a header {@code name}/{@code value} pair should be treated as
* sensitive.
*
* @return {@link BiPredicate}<{@link CharSequence}, {@link CharSequence}> that
* returns {@code true} if a header <{@code name}, {@code value}> pair should be treated as
* sensitive, {@code false} otherwise
*/
BiPredicate headersSensitivityDetector();
/**
* Get the logger configuration for HTTP/2 frames.
*
* @return the logger configuration to use for HTTP/2 frames or {@code null} to disable it.
*/
@Nullable
UserDataLoggerConfig frameLoggerConfig();
/**
* Configured {@link KeepAlivePolicy}.
*
* @return configured {@link KeepAlivePolicy}.
*/
KeepAlivePolicy keepAlivePolicy();
/**
* Get the {@link Http2Settings} that provides a hint for the initial settings. Note that some settings may be
* ignored if not supported (e.g. push promise).
* @return the {@link Http2Settings} that provides a hint for the initial settings. Note that some settings may be
* ignored if not supported (e.g. push promise).
*/
default Http2Settings initialSettings() { // FIXME: 0.43 - consider removing default impl
throw new UnsupportedOperationException("H2ProtocolConfig#initialSettings() is not supported by " + getClass());
}
/**
* Provide a hint on the number of bytes that the flow controller will attempt to give to a stream for each
* allocation (assuming the stream has this much eligible data).
*
* This maybe useful because the amount of bytes the local peer is permitted to write is limited based upon the
* remote peer's flow control window for each stream. Some flow controllers iterate over all streams (and may
* consider stream priority) that have data
* pending to write and allow them to write a subset of the available flow control window (aka a "quantum"). The
* larger this value may result in increased goodput/throughput on the connection, but increase latency on some
* streams (if flow control windows become constrained).
* @return number of bytes.
*/
default int flowControlQuantum() { // FIXME: 0.43 - consider removing default impl
throw new UnsupportedOperationException("H2ProtocolConfig#flowControlQuantum() is not supported by " +
getClass());
}
/**
* Number of bytes to increment via WINDOW_UPDATE
* for the connection. This value is applied on top of {@link Http2Settings#initialWindowSize()} from
* {@link #initialSettings()} for the connection (as opposed to individual request streams). This can be helpful to
* avoid a single stream consuming all the flow control credits.
* @return The number of bytes to increment the local flow control window for the connection.
*/
default int flowControlWindowIncrement() { // FIXME: 0.43 - consider removing default impl
throw new UnsupportedOperationException("H2ProtocolConfig#flowControlWindowIncrement() is not supported by " +
getClass());
}
/**
* A policy for sending PING frames to the peer.
*
* While {@link #idleDuration()} and {@link #ackTimeout()}} can be configured independently, users should keep
* them reasonably aligned. When {@link #idleDuration() idle duration} is positive, the system expects to receive
* {@code PING} acknowledgment before it can send the following {@code PING} frames. A good practice is to keep
* {@link #ackTimeout()} less than or equal to {@link #idleDuration()}}. Otherwise, the following {@code PING}
* frames can be delayed awaiting acknowledgment of the previous one.
*/
interface KeepAlivePolicy {
/**
* {@link Duration} of time the connection has to be idle before a
* ping is sent.
*
* Too short idle duration can be used for testing but may cause unnecessarily high network traffic in real
* environments. {@link Duration#ZERO} disables keep-alive {@code PING} frames. In this case,
* {@link #ackTimeout()} is still used for {@code PING} acknowledgment during graceful closure process between
* two GOAWAY frames.
*
* @return {@link Duration} of time the connection has to be idle before a
* ping is sent or {@link Duration#ZERO} to
* disable keep-alive {@code PING} frames.
*/
Duration idleDuration();
/**
* {@link Duration} to wait for acknowledgment from the peer after a
* ping is sent. If no acknowledgment is received
* within the configured timeout, a connection will be closed.
*
* This duration must be positive. Too short ack timeout can cause undesirable connection closures. Too long ack
* timeout can add unnecessary delay when the remote peer is unresponsive or the network connection is broken,
* because under normal circumstances {@code PING} frames ara acknowledged immediately.
*
* When {@link #idleDuration()} is {@link Duration#ZERO zero}, this timeout is still used for {@code PING}
* acknowledgment during graceful closure process between two
* GOAWAY frames.
*
* @return {@link Duration} to wait for acknowledgment from the peer after a
* ping is sent.
*/
Duration ackTimeout();
/**
* Whether this policy allows to send pings
* even if there are no streams active on the connection.
*
* @return {@code true} if this policy allows to send
* pings even if there are no streams active on
* the connection.
*/
boolean withoutActiveStreams();
}
}