Class TrafficResilienceHttpServiceFilter.Builder
- Enclosing class:
- TrafficResilienceHttpServiceFilter
TrafficResilienceHttpServiceFilter
instance builder.-
Constructor Summary
ConstructorsConstructorDescriptionBuilder
(Supplier<CapacityLimiter> capacityLimiterSupplier) ATrafficResilienceHttpServiceFilter
with no partitioning schemes.Builder
(Supplier<Function<HttpRequestMetaData, CapacityLimiter>> capacityPartitionsSupplier, boolean rejectNotMatched) ATrafficResilienceHttpServiceFilter
can support request partitioning schemes. -
Method Summary
Modifier and TypeMethodDescriptionbuild()
Invoke to build an instance ofTrafficResilienceHttpServiceFilter
filter to be used inside theHttpServerBuilder
.capacityPartitions
(Supplier<Function<HttpRequestMetaData, CapacityLimiter>> capacityPartitionsSupplier, boolean rejectNotMatched) DefineCapacityLimiter
partitions.circuitBreakerPartitions
(Supplier<Function<HttpRequestMetaData, CircuitBreaker>> circuitBreakerPartitionsSupplier) DefineCircuitBreaker
partitions to manage local errors.classifier
(Supplier<Function<HttpRequestMetaData, Classification>> classifier) Classification in the context of capacity management allows for hints to the relevantCapacityLimiter
to be influenced on the decision making process by the class of therequest
.dryRun
(boolean dryRun) Use the resilience filter in dry-run mode.observer
(TrafficResiliencyObserver observer) Provide an observer to track interactions of the filter and requests.onCancelTicketTerminal
(Consumer<CapacityLimiter.Ticket> onCancellation) Ticket
terminal callback override upon cancellation of the operation.Ticket
terminal callback override upon erroneous completion of the operation.Defines theServiceRejectionPolicy
which in turn defines the behavior of the service when a rejection occurs due tocapacity
orbreaker
.
-
Constructor Details
-
Builder
ATrafficResilienceHttpServiceFilter
with no partitioning schemes.All requests will go through the provided
CapacityLimiter
.- Parameters:
capacityLimiterSupplier
- TheSupplier
to create a newCapacityLimiter
for each new filter created by thisfactory
.
-
Builder
public Builder(Supplier<Function<HttpRequestMetaData, CapacityLimiter>> capacityPartitionsSupplier, boolean rejectNotMatched) ATrafficResilienceHttpServiceFilter
can support request partitioning schemes.A partition in the context of capacity management, is a set of requests that represent an application characteristic relevant to capacity, which can be isolated and have their own set of rules (ie.
CapacityLimiter
).An example of a partition can be to represent each customer in a multi-tenant service. If an application wants to introduce customer API quotas, they can do so by identifying that customer through the
HttpRequestMetaData
and providing a differentCapacityLimiter
for that customer.If a
partitions
doesn't return aCapacityLimiter
for the givenHttpRequestMetaData
then therejectNotMatched
is evaluated to decide what the filter should do with this request. Iftrue
then the request will berejected
.It's important that instances returned from this
mapper
are singletons and shared across the same matched partitions. Otherwise, capacity will not be controlled as expected, and there is also the risk forOutOfMemoryError
.- Parameters:
capacityPartitionsSupplier
- ASupplier
to create a newFunction
for each new filter created by thisfactory
. Function provides aCapacityLimiter
instance for the givenHttpRequestMetaData
.rejectNotMatched
- Flag that decides what the filter should do whenpartitions
doesn't return aCapacityLimiter
.
-
-
Method Details
-
capacityPartitions
public TrafficResilienceHttpServiceFilter.Builder capacityPartitions(Supplier<Function<HttpRequestMetaData, CapacityLimiter>> capacityPartitionsSupplier, boolean rejectNotMatched) DefineCapacityLimiter
partitions.A partition in the context of capacity management, is a set of requests that represent an application characteristic relevant to capacity, which can be isolated and have their own set of rules (i.e.
CapacityLimiter
).An example of a partition can be to represent each customer in a multi-tenant service. If an application wants to introduce customer API quotas, they can do so by identifying that customer through the
HttpRequestMetaData
and providing a differentCapacityLimiter
for that customer.If a
partitions
doesn't return aCapacityLimiter
for the givenHttpRequestMetaData
then therejectNotMatched
is evaluated to decide what the filter should do with this request. Iftrue
then the request will berejected
.It's important that instances returned from this
mapper
are singletons and shared across the same matched partitions. Otherwise, capacity will not be controlled as expected, and there is also the risk forOutOfMemoryError
.- Parameters:
capacityPartitionsSupplier
- ASupplier
to create a newFunction
for each new filter created by thisfactory
. Function provides aCapacityLimiter
instance for the givenHttpRequestMetaData
.rejectNotMatched
- Flag that decides what the filter should do whenpartitions
doesn't return aCapacityLimiter
.- Returns:
this
.
-
classifier
public TrafficResilienceHttpServiceFilter.Builder classifier(Supplier<Function<HttpRequestMetaData, Classification>> classifier) Classification in the context of capacity management allows for hints to the relevantCapacityLimiter
to be influenced on the decision making process by the class of therequest
.An example of classification, could be health checks that need to be given preference and still allowed a permit even under stress conditions. Another case, could be a separation of reads and writes, giving preference to the reads will result in a more available system under stress, by rejecting earlier writes.
The behavior of the classification and their thresholds could be different among different
CapacityLimiter
implementations, therefore the use of this API requires good understanding of how the algorithm in use will react for the different classifications.Classification work within the context of a single
Builder(Supplier, boolean)
partition} and not universally in the filter.- Parameters:
classifier
- ASupplier
of aFunction
that maps an incomingHttpRequestMetaData
to aClassification
.- Returns:
this
.
-
circuitBreakerPartitions
public TrafficResilienceHttpServiceFilter.Builder circuitBreakerPartitions(Supplier<Function<HttpRequestMetaData, CircuitBreaker>> circuitBreakerPartitionsSupplier) DefineCircuitBreaker
partitions to manage local errors.The breakers can either be universal or follow any partitioning scheme (i.e., API / service-path, customer e.t.c) but is recommended to follow similar schematics between service and client if possible for best experience.
Once a matching
CircuitBreaker
transitions to open state, requests that match the same breaker will fail (e.g.,HttpResponseStatus.SERVICE_UNAVAILABLE
) andServiceRejectionPolicy.onOpenCircuitRetryAfter()
can be used to hint peers about the fact that the circuit will remain open for a certain amount of time.- Parameters:
circuitBreakerPartitionsSupplier
- ASupplier
to create a newFunction
for each new filter created by thisfactory
. Function provides aCircuitBreaker
instance for the givenHttpRequestMetaData
.- Returns:
this
.
-
onErrorTicketTerminal
public TrafficResilienceHttpServiceFilter.Builder onErrorTicketTerminal(BiConsumer<CapacityLimiter.Ticket, Throwable> onError) Ticket
terminal callback override upon erroneous completion of the operation. Erroneous completion in this context means, that an error occurred for either theSingle
or thePublisher
of the operation. By default, the terminal callback isCapacityLimiter.Ticket.failed(Throwable)
.- Parameters:
onError
- Callback to override defaultticket
terminal event for an erroneous operation.- Returns:
this
.
-
onCancelTicketTerminal
public TrafficResilienceHttpServiceFilter.Builder onCancelTicketTerminal(Consumer<CapacityLimiter.Ticket> onCancellation) Ticket
terminal callback override upon cancellation of the operation. By default, the terminal callback isCapacityLimiter.Ticket.ignored()
.You may need to adjust this callback depending on the ordering this filter was applied. For example if the filter is applied after the
timeout-filter
then you may want to alsodrop the ticket
to let the algorithm apply throttling accounting for this timeout.- Parameters:
onCancellation
- Callback to override defaultticket
terminal event when an operation is cancelled.- Returns:
this
.
-
rejectionPolicy
Defines theServiceRejectionPolicy
which in turn defines the behavior of the service when a rejection occurs due tocapacity
orbreaker
.- Parameters:
policy
- The policy to put into effect when a rejection occurs.- Returns:
this
.- See Also:
-
observer
Provide an observer to track interactions of the filter and requests.- Parameters:
observer
- an observer to track interactions of the filter and requests.- Returns:
this
.
-
dryRun
Use the resilience filter in dry-run mode. In dry-run mode the capacity limiter will track requests and log their results but request which would have been rejected will instead pass through to the underlying client.- Parameters:
dryRun
- whether to use the resilience filter in dry-run mode.- Returns:
this
-
build
Invoke to build an instance ofTrafficResilienceHttpServiceFilter
filter to be used inside theHttpServerBuilder
.- Returns:
- An instance of
TrafficResilienceHttpServiceFilter
with the characteristics of this builder input.
-