• Stars
    star
    292
  • Rank 142,152 (Top 3 %)
  • Language
    Java
  • License
    MIT License
  • Created over 9 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Client-side response routing for Spring

Riptide: A next generation HTTP client

Tidal wave

Stability: Active Build Status Coverage Status Code Quality Javadoc Release Maven Central License

Riptide noun, /ˈrΙͺp.taΙͺd/: strong flow of water away from the shore

Riptide is a library that implements client-side response routing. It tries to fill the gap between the HTTP protocol and Java. Riptide allows users to leverage the power of HTTP with its unique API.

  • Technology stack: Based on spring-web and uses the same foundation as Spring's RestTemplate.
  • Status: Actively maintained and used in production.
  • Riptide is unique in the way that it doesn't abstract HTTP away, but rather embraces it!

🚨 If you want to upgrade from an older version to the latest one, consult the following migration guides:

Example

Usage typically looks like this:

http.get("/repos/{org}/{repo}/contributors", "zalando", "riptide")
    .dispatch(series(),
        on(SUCCESSFUL).call(listOf(User.class), users -> 
            users.forEach(System.out::println)));

Feel free to compare this e.g. to Feign or Retrofit.

Features

Origin

Most modern clients try to adapt HTTP to a single-return paradigm as shown in the following example. Even though this may be perfectly suitable for most applications, it takes away a lot of the power that comes with HTTP. It's not easy to support multiple return values, i.e. distinct happy cases. Access to response headers or manual content negotiation are also more difficult.

@GET
@Path("/repos/{org}/{repo}/contributors")
List<User> getContributors(@PathParam String org, @PathParam String repo);

Riptide tries to counter this by providing a different approach to leverage the power of HTTP. Go checkout the concept document for more details.

Dependencies

  • Java 17
  • Spring 6

Installation

Add the following dependency to your project:

<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>riptide-core</artifactId>
    <version>${riptide.version}</version>
</dependency>

Additional modules/artifacts of Riptide always share the same version number.

Alternatively, you can import our bill of materials...

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.zalando</groupId>
      <artifactId>riptide-bom</artifactId>
      <version>${riptide.version}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

... which allows you to omit versions:

<dependencies>
  <dependency>
      <groupId>org.zalando</groupId>
      <artifactId>riptide-core</artifactId>
  </dependency>
  <dependency>
      <groupId>org.zalando</groupId>
      <artifactId>riptide-failsafe</artifactId>
  </dependency>
  <dependency>
      <groupId>org.zalando</groupId>
      <artifactId>riptide-faults</artifactId>
  </dependency>
</dependencies>

Configuration

Integration of your typical Spring Boot Application with Riptide, Logbook and Tracer can be greatly simplified by using the Riptide: Spring Boot Starter. Go check it out!

Http.builder()
    .executor(Executors.newCachedThreadPool())
    .requestFactory(new HttpComponentsClientHttpRequestFactory())
    .baseUrl("https://api.github.com")
    .converter(new MappingJackson2HttpMessageConverter())
    .converter(new Jaxb2RootElementHttpMessageConverter())
    .plugin(new OriginalStackTracePlugin())
    .build();

The following code is the bare minimum, since a request factory is required:

Http.builder()
    .executor(Executors.newCachedThreadPool())
    .requestFactory(new HttpComponentsClientHttpRequestFactory())
    .build();

This defaults to:

Thread Pool

All off the standard Executors.new*Pool() implementations only support the queue-first style, i.e. the pool scales up to the core pool size, then fills the queue and only then will scale up to the maximum pool size.

Riptide provides a ThreadPoolExecutors.builder() which also offers a scale-first style where thread pools scale up to the maximum pool size before they queue any tasks. That usually leads to higher throughput, lower latency on the expense of having to maintain more threads.

The following table shows which combination of properties are supported

Configuration Supported
Without queue, fixed sizeΒΉ βœ”οΈ
Without queue, elastic sizeΒ² βœ”οΈ
Bounded queue, fixed size βœ”οΈ
Bounded queue, elastic size βœ”οΈ
Unbounded queue, fixed size βœ”οΈ
Unbounded queue, elastic size ❌³
Scale first, without queue, fixed size ❌⁴
Scale first, without queue, elastic size ❌⁴
Scale first, bounded queue, fixed size ❌⁡
Scale first, bounded queue, elastic size βœ”οΈβΆ
Scale first, unbounded queue, fixed size ❌⁡
Scale first, unbounded queue, elastic size βœ”οΈβΆ

ΒΉ Core pool size = maximum pool size
Β² Core pool size < maximum pool size
Β³ Pool can't grow past core pool size due to unbounded queue
⁴ Scale first has no meaning without a queue
⁡ Fixed size pools are already scaled up
⁢ Elastic, but only between 0 and maximum pool size

Examples

  1. Without queue, elastic size

    ThreadPoolExecutors.builder()
        .withoutQueue()
        .elasticSize(5, 20)
        .keepAlive(1, MINUTES)
        .build()
  2. Bounded queue, fixed size

    ThreadPoolExecutors.builder()
        .boundedQueue(20)
        .fixedSize(20)
        .keepAlive(1, MINUTES)
        .build()
  3. Scale-first, unbounded queue, elastic size

    ThreadPoolExecutors.builder()
        .scaleFirst()
        .unboundedQueue()
        .elasticSize(20)   
        .keepAlive(1, MINUTES)
        .build()

You can read more about scale-first here:

In order to configure the thread pool correctly, please refer to How to set an ideal thread pool size.

Non-blocking IO

🚨 While the previous versions of Riptide supported both, blocking and non-blocking request factories, due to the removal of AsyncClientHttpRequestFactory in Spring 6, Riptide 4 only supports blocking request factories:

In order to provide asynchrony for blocking IO you need to register an executor. Not passing an executor will make all network communication synchronous, i.e. all futures returned by Riptide will already be completed.

Synchronous Asynchronous
ClientHttpRequestFactory Executor + ClientHttpRequestFactory

Usage

Requests

A full-blown request may contain any of the following aspects: HTTP method, request URI, query parameters, headers and a body:

http.post("/sales-order")
    .queryParam("async", "false")
    .contentType(CART)
    .accept(SALES_ORDER)
    .header("Client-IP", "127.0.0.1")
    .body(cart)
    //...

Riptide supports the following HTTP methods: get, head, post, put, patch, delete, options and trace respectively. Query parameters can either be provided individually using queryParam(String, String) or multiple at once with queryParams(Multimap<String, String>).

The following operations are applied to URI Templates (get(String, Object...)) and URIs (get(URI)) respectively:

URI Template

URI

  • none, used as is
  • expected to be already encoded

Both

  • after respective transformation
  • resolved against Base URL (if present)
  • Query String (merged with existing)
  • Normalization

The URI Resolution table shows some examples how URIs are resolved against Base URLs, based on the chosen resolution strategy.

The Content-Type- and Accept-header have type-safe methods in addition to the generic support that is header(String, String) and headers(HttpHeaders).

Responses

Riptide is special in the way it handles responses. Rather than having a single return value, you need to register callbacks. Traditionally, you would attach different callbacks for different response status codes. Alternatively, there are built-in routing capabilities on status code families (called series in Spring) as well as on content types.

http.post("/sales-order")
    // ...
    .dispatch(series(),
        on(SUCCESSFUL).dispatch(contentType(),
            on(SALES_ORDER).call(SalesOrder.class, this::persist),
        on(CLIENT_ERROR).dispatch(status(),
            on(CONFLICT).call(this::retry),
            on(PRECONDITION_FAILED).call(this::readAgainAndRetry),
            anyStatus().call(problemHandling())),
        on(SERVER_ERROR).dispatch(status(),
            on(SERVICE_UNAVAILABLE).call(this::scheduleRetryLater))));

The callbacks can have the following signatures:

persist(SalesOrder)
retry(ClientHttpResponse)
scheduleRetryLater()

Futures

Riptide will return a CompletableFuture<ClientHttpResponse>. That means you can choose to chain transformations/callbacks or block on it.

If you need proper return values take a look at Riptide: Capture.

Exceptions

The only special custom exception you may receive is UnexpectedResponseException, if and only if there was no matching condition and no wildcard condition.

Plugins

Riptide comes with a way to register extensions in the form of plugins.

  • OriginalStackTracePlugin, preserves stack traces when executing requests asynchronously
  • AuthorizationPlugin, adds Authorization support
  • FailsafePlugin, adds retries, circuit breaker, backup requests and timeout support
  • MicrometerPlugin, adds metrics for request duration
  • TransientFaults, detects transient faults, e.g. network issues

Whenever you encounter the need to perform some repetitive task on the futures returned by a remote call, you may consider implementing a custom Plugin for it.

Plugins are executed in phases:

Plugin phases

Please consult the Plugin documentation for details.

Testing

Riptide is built on the same foundation as Spring's RestTemplate. That allows us, with a small trick, to use the same testing facilities, the MockRestServiceServer:

RestTemplate template = new RestTemplate();
MockRestServiceServer server = MockRestServiceServer.createServer(template);
ClientHttpRequestFactory requestFactory = template.getRequestFactory();

Http.builder()
    .requestFactory(requestFactory)
    // continue configuration

We basically use an intermediate RestTemplate as a holder of the special ClientHttpRequestFactory that the MockRestServiceServer manages.

If you are using Spring Boot Starter, the test setup is provided by a convenient annotation @RiptideClientTest. See here.

Getting help

If you have questions, concerns, bug reports, etc., please file an issue in this repository's Issue Tracker.

Getting involved/Contributing

To contribute, simply make a pull request and add a brief description (1-2 sentences) of your addition or change. For more details check the contribution guidelines.

Credits and references

More Repositories

1

patroni

A template for PostgreSQL High Availability with Etcd, Consul, ZooKeeper, or Kubernetes
Python
6,267
star
2

postgres-operator

Postgres operator creates and manages PostgreSQL clusters running in Kubernetes
Go
3,686
star
3

skipper

An HTTP router and reverse proxy for service composition, including use cases like Kubernetes Ingress
Go
3,088
star
4

restful-api-guidelines

A model set of guidelines for RESTful APIs and Events, created by Zalando
CSS
2,605
star
5

zalenium

A flexible and scalable container based Selenium Grid with video recording, live preview, basic auth & dashboard.
Java
2,385
star
6

SwiftMonkey

A framework for doing randomised UI testing of iOS apps
Swift
1,947
star
7

logbook

An extensible Java library for HTTP request and response logging
Java
1,788
star
8

tailor

A streaming layout service for front-end microservices
JavaScript
1,728
star
9

tech-radar

Visualizing our technology choices
1,581
star
10

spilo

Highly available elephant herd: HA PostgreSQL cluster using Docker
Python
1,225
star
11

intellij-swagger

A plugin to help you easily edit Swagger and OpenAPI specification files inside IntelliJ IDEA
Java
1,172
star
12

problem-spring-web

A library for handling Problems in Spring Web MVC
Java
1,031
star
13

nakadi

A distributed event bus that implements a RESTful API abstraction on top of Kafka-like queues
Java
928
star
14

zally

A minimalistic, simple-to-use API linter
Kotlin
903
star
15

problem

A Java library that implements application/problem+json
Java
869
star
16

zalando-howto-open-source

Open Source guidance from Zalando, Europe's largest online fashion platform
799
star
17

go-keyring

Cross-platform keyring interface for Go
Go
689
star
18

gin-oauth2

Middleware for Gin Framework users who also want to use OAuth2
Go
579
star
19

zappr

An agent that enforces guidelines for your GitHub repositories
JavaScript
542
star
20

pg_view

Get a detailed, real-time view of your PostgreSQL database and system metrics
Python
494
star
21

engineering-principles

Our guidelines for building new applications and managing legacy systems
376
star
22

gulp-check-unused-css

A build tool for checking your HTML templates for unused CSS classes
CSS
359
star
23

zmon

Real-time monitoring of critical metrics & KPIs via elegant dashboards, Grafana3 visualizations & more
Shell
355
star
24

expan

Open-source Python library for statistical analysis of randomised control trials (A/B tests)
Python
325
star
25

PGObserver

A battle-tested, flexible & comprehensive monitoring solution for your PostgreSQL databases
Python
316
star
26

jackson-datatype-money

Extension module to properly support datatypes of javax.money
Java
240
star
27

grafter

Grafter is a library to configure and wire Scala applications
Scala
240
star
28

opentracing-toolbox

Best-of-breed OpenTracing utilities, instrumentations and extensions
Java
180
star
29

elm-street-404

A fun WebGL game built with Elm
Elm
176
star
30

tokens

Java library for conveniently verifying and storing OAuth 2.0 service access tokens
Java
169
star
31

innkeeper

Simple route management API for Skipper
Scala
166
star
32

public-presentations

List of public talks by Zalando Tech: meetup presentations, recorded conference talks, slides
165
star
33

python-nsenter

Enter kernel namespaces from Python
Python
139
star
34

faux-pas

A library that simplifies error handling for Functional Programming in Java
Java
132
star
35

dress-code

The official style guide and framework for all Zalando Brand Solutions products
CSS
129
star
36

beard

A lightweight, logicless templating engine, written in Scala and inspired by Mustache
Scala
121
star
37

friboo

Utility library for writing microservices in Clojure, with support for Swagger and OAuth
Clojure
117
star
38

spring-cloud-config-aws-kms

Spring Cloud Config add-on that provides encryption via AWS KMS
Java
99
star
39

zalando.github.io

Open Source Documentation and guidelines for Zalando developers
HTML
86
star
40

failsafe-actuator

Endpoint library for the failsafe framework
Java
52
star
41

package-build

A toolset for building system packages using Docker and fpm-cookery
Ruby
35
star
42

ghe-backup

Github Enterprise backup at ZalandoTech (Kubernetes, AWS, Docker)
Shell
30
star
43

rds-health

discover anomalies, performance issues and optimization within AWS RDS
Go
26
star
44

backstage-plugin-api-linter

API Linter is a quality assurance tool that checks the compliance of API's specifications to Zalando's API rules.
TypeScript
12
star
45

.github

Standard github health files
1
star