{"id":13485857,"url":"https://github.com/zalando/riptide","last_synced_at":"2025-03-27T19:31:53.866Z","repository":{"id":30011373,"uuid":"33559545","full_name":"zalando/riptide","owner":"zalando","description":"Client-side response routing for Spring","archived":false,"fork":false,"pushed_at":"2025-03-06T08:17:59.000Z","size":8361,"stargazers_count":312,"open_issues_count":22,"forks_count":72,"subscribers_count":22,"default_branch":"main","last_synced_at":"2025-03-06T09:35:32.895Z","etag":null,"topics":["async","client-side","http","java","json-stream","microservices","plugin-extension","resilience","routing","spring","spring-boot-starter","web"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zalando.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-04-07T18:03:31.000Z","updated_at":"2025-03-06T08:17:59.000Z","dependencies_parsed_at":"2023-02-19T20:15:57.551Z","dependency_job_id":"3546f6d3-02b3-4f7a-be19-c67bcfa5786e","html_url":"https://github.com/zalando/riptide","commit_stats":null,"previous_names":[],"tags_count":85,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zalando%2Friptide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zalando%2Friptide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zalando%2Friptide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zalando%2Friptide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zalando","download_url":"https://codeload.github.com/zalando/riptide/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245910936,"owners_count":20692519,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["async","client-side","http","java","json-stream","microservices","plugin-extension","resilience","routing","spring","spring-boot-starter","web"],"created_at":"2024-07-31T18:00:32.801Z","updated_at":"2025-03-27T19:31:51.614Z","avatar_url":"https://github.com/zalando.png","language":"Java","readme":"# Riptide: A next generation HTTP client \n\n[![Tidal wave](docs/wave.jpg)](http://pixabay.com/en/wave-water-sea-tsunami-giant-wave-11061/)\n\n[![Stability: Active](https://masterminds.github.io/stability/active.svg)](https://masterminds.github.io/stability/active.html)\n![Build Status](https://github.com/zalando/riptide/workflows/build/badge.svg)\n[![Coverage Status](https://img.shields.io/coveralls/zalando/riptide/main.svg)](https://coveralls.io/r/zalando/riptide)\n[![Code Quality](https://img.shields.io/codacy/grade/1fbe3d16ca544c0c8589692632d114de/main.svg)](https://www.codacy.com/app/whiskeysierra/riptide)\n[![Javadoc](https://www.javadoc.io/badge/org.zalando/riptide-core.svg)](http://www.javadoc.io/doc/org.zalando/riptide-core)\n[![Release](https://img.shields.io/github/release/zalando/riptide.svg)](https://github.com/zalando/riptide/releases)\n[![Maven Central](https://img.shields.io/maven-central/v/org.zalando/riptide-core.svg)](https://maven-badges.herokuapp.com/maven-central/org.zalando/riptide-core)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/zalando/riptide/main/LICENSE)\n\n\u003e **Riptide** noun, /ˈrɪp.taɪd/: strong flow of water away from the shore\n\n*Riptide* is a library that implements ***client-side response routing***.  It tries to fill the gap between the HTTP\nprotocol and Java. Riptide allows users to leverage the power of HTTP with its unique API.\n\n- **Technology stack**: Based on `spring-web` and uses the same foundation as Spring's RestTemplate.\n- **Status**:  Actively maintained and used in production.\n- Riptide is unique in the way that it doesn't abstract HTTP away, but rather embraces it!\n\n:rotating_light: If you want to upgrade from an older version to the latest one, consult the following migration guides:\n - **Upgrading from 3.x to 4.x?** Please refer to the [Migration Guide](MIGRATION.md#riptide-40-migration-guide).\n - **Upgrading from 2.x to 3.x?** Please refer to the [Migration Guide](MIGRATION.md#riptide-30-migration-guide).\n\n## Example\n\nUsage typically looks like this:\n\n```java\nhttp.get(\"/repos/{org}/{repo}/contributors\", \"zalando\", \"riptide\")\n    .dispatch(series(),\n        on(SUCCESSFUL).call(listOf(User.class), users -\u003e \n            users.forEach(System.out::println)));\n```\n\nFeel free to compare this e.g. to [Feign](https://github.com/Netflix/feign#basics) or\n[Retrofit](https://github.com/square/retrofit/blob/master/samples/src/main/java/com/example/retrofit/SimpleService.java).\n\n## Features\n- full access to the underlying HTTP client\n- [resilience](docs/resilience.md) built into it\n  - isolated thread pools, connection pools and bounded queues\n  - transient fault detection via [riptide-faults](riptide-faults)\n  - retries, circuit breaker, backup requests and timeouts via [Failsafe integration](riptide-failsafe)\n- non-blocking IO (optional)\n- encourages the use of\n  - fallbacks\n  - content negotiation\n  - robust error handling\n- elegant syntax\n- type-safe\n- asynchronous by default\n- [synchronous return values](riptide-capture) on demand\n- [`application/problem+json` support](riptide-problem)\n- [streaming](riptide-stream)\n\n## Origin\n\nMost modern clients try to adapt HTTP to a single-return paradigm as shown in the following example. Even though this\nmay be perfectly suitable for most applications, it takes away a lot of the power that comes with HTTP. It's not easy to\nsupport multiple return values, i.e. distinct happy cases. Access to response headers or manual content\nnegotiation are also more difficult.\n \n```java\n@GET\n@Path(\"/repos/{org}/{repo}/contributors\")\nList\u003cUser\u003e getContributors(@PathParam String org, @PathParam String repo);\n```\nRiptide tries to counter this by providing a different approach to leverage the power of HTTP.\nGo checkout the [concept document](docs/concepts.md) for more details.\n\n## Dependencies\n\n- Java 17\n- Spring 6\n\n## Installation\n\nAdd the following dependency to your project:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.zalando\u003c/groupId\u003e\n    \u003cartifactId\u003eriptide-core\u003c/artifactId\u003e\n    \u003cversion\u003e${riptide.version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nAdditional modules/artifacts of Riptide always share the same version number.\n\nAlternatively, you can import our *bill of materials*...\n\n```xml\n\u003cdependencyManagement\u003e\n  \u003cdependencies\u003e\n    \u003cdependency\u003e\n      \u003cgroupId\u003eorg.zalando\u003c/groupId\u003e\n      \u003cartifactId\u003eriptide-bom\u003c/artifactId\u003e\n      \u003cversion\u003e${riptide.version}\u003c/version\u003e\n      \u003ctype\u003epom\u003c/type\u003e\n      \u003cscope\u003eimport\u003c/scope\u003e\n    \u003c/dependency\u003e\n  \u003c/dependencies\u003e\n\u003c/dependencyManagement\u003e\n```\n\n... which allows you to omit versions:\n\n```xml\n\u003cdependencies\u003e\n  \u003cdependency\u003e\n      \u003cgroupId\u003eorg.zalando\u003c/groupId\u003e\n      \u003cartifactId\u003eriptide-core\u003c/artifactId\u003e\n  \u003c/dependency\u003e\n  \u003cdependency\u003e\n      \u003cgroupId\u003eorg.zalando\u003c/groupId\u003e\n      \u003cartifactId\u003eriptide-failsafe\u003c/artifactId\u003e\n  \u003c/dependency\u003e\n  \u003cdependency\u003e\n      \u003cgroupId\u003eorg.zalando\u003c/groupId\u003e\n      \u003cartifactId\u003eriptide-faults\u003c/artifactId\u003e\n  \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\n## Configuration\n\nIntegration of your typical Spring Boot Application with Riptide, [Logbook](https://github.com/zalando/logbook) and\n[Tracer](https://github.com/zalando/tracer) can be greatly simplified by using the\n[**Riptide: Spring Boot Starter**](riptide-spring-boot-starter). Go check it out!\n\n```java\nHttp.builder()\n    .executor(Executors.newCachedThreadPool())\n    .requestFactory(new HttpComponentsClientHttpRequestFactory())\n    .baseUrl(\"https://api.github.com\")\n    .converter(new MappingJackson2HttpMessageConverter())\n    .converter(new Jaxb2RootElementHttpMessageConverter())\n    .plugin(new OriginalStackTracePlugin())\n    .build();\n```\n\nThe following code is the bare minimum, since a request factory is required:\n\n```java\nHttp.builder()\n    .executor(Executors.newCachedThreadPool())\n    .requestFactory(new HttpComponentsClientHttpRequestFactory())\n    .build();\n```\n\nThis defaults to:\n- no base URL\n- same list of converters as `new RestTemplate()`\n- [`OriginalStackTracePlugin`](#plugins)\n\n### Thread Pool\n\nAll 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.\n\nRiptide 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. \n\nThe following table shows which combination of properties are supported\n\n| Configuration                              | Supported           |\n|--------------------------------------------|---------------------|\n| Without queue, fixed size¹                 | :heavy_check_mark:  |\n| Without queue, elastic size²               | :heavy_check_mark:  |\n| Bounded queue, fixed size                  | :heavy_check_mark:  |\n| Bounded queue, elastic size                | :heavy_check_mark:  |\n| Unbounded queue, fixed size                | :heavy_check_mark:  |\n| Unbounded queue, elastic size              | :x:³                |\n| Scale first, without queue, fixed size     | :x:⁴                |\n| Scale first, without queue, elastic size   | :x:⁴                |\n| Scale first, bounded queue, fixed size     | :x:⁵                |\n| Scale first, bounded queue, elastic size   | :heavy_check_mark:⁶ |\n| Scale first, unbounded queue, fixed size   | :x:⁵                |\n| Scale first, unbounded queue, elastic size | :heavy_check_mark:⁶ |\n\n¹ Core pool size = maximum pool size  \n² Core pool size \u003c maximum pool size  \n³ Pool can't grow past core pool size due to unbounded queue  \n⁴ Scale *first* has no meaning without a queue    \n⁵ Fixed size pools are already scaled up  \n⁶ Elastic, but only between **0** and maximum pool size  \n\n#### Examples\n\n1. Without queue, elastic size\n\n    ```java\n    ThreadPoolExecutors.builder()\n        .withoutQueue()\n        .elasticSize(5, 20)\n        .keepAlive(1, MINUTES)\n        .build()\n    ```\n\n2. Bounded queue, fixed size\n\n    ```java\n    ThreadPoolExecutors.builder()\n        .boundedQueue(20)\n        .fixedSize(20)\n        .keepAlive(1, MINUTES)\n        .build()\n    ```\n\n3. Scale-first, unbounded queue, elastic size\n\n    ```java\n    ThreadPoolExecutors.builder()\n        .scaleFirst()\n        .unboundedQueue()\n        .elasticSize(20)   \n        .keepAlive(1, MINUTES)\n        .build()\n    ```\n\nYou can read more about *scale-first* here:\n- [Java Scale First ExecutorService — A myth or a reality](https://medium.com/@uditharosha/java-scale-first-executorservice-4245a63222df)\n- [How to get the ThreadPoolExecutor to increase threads to max before queueing?](https://stackoverflow.com/questions/19528304/how-to-get-the-threadpoolexecutor-to-increase-threads-to-max-before-queueing)\n\nIn order to configure the thread pool correctly, please refer to\n[How to set an ideal thread pool size](https://jobs.zalando.com/tech/blog/how-to-set-an-ideal-thread-pool-size).\n\n### Non-blocking IO\n\n:rotating_light: While the previous versions of Riptide supported both, blocking and non-blocking request factories,\ndue to the removal of `AsyncClientHttpRequestFactory` in Spring 6, Riptide 4 only supports blocking request factories:\n\n- [`ApacheClientHttpRequestFactory`](riptide-httpclient), using the [Apache HTTP Client](https://hc.apache.org/httpcomponents-client-ga/)\n- ~[`HttpComponentsClientHttpRequestFactory`](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/http/client/HttpComponentsClientHttpRequestFactory.html)~, please use the one above\n- [`SimpleClientHttpRequestFactory`](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/http/client/SimpleClientHttpRequestFactory.html), using [`HttpURLConnection`](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/net/HttpURLConnection.html)\n- [`OkHttp3ClientHttpRequestFactory`](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/http/client/OkHttp3ClientHttpRequestFactory.html), using [OkHttp](https://square.github.io/okhttp/)\n\nIn 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.\n\n| Synchronous                | Asynchronous                            |\n|----------------------------|-----------------------------------------|\n| `ClientHttpRequestFactory` | `Executor` + `ClientHttpRequestFactory` |\n\n## Usage\n\n### Requests\n\nA full-blown request may contain any of the following aspects: HTTP method, request URI, query parameters,\nheaders and a body:\n\n```java\nhttp.post(\"/sales-order\")\n    .queryParam(\"async\", \"false\")\n    .contentType(CART)\n    .accept(SALES_ORDER)\n    .header(\"Client-IP\", \"127.0.0.1\")\n    .body(cart)\n    //...\n```\n\nRiptide supports the following HTTP methods: `get`, `head`, `post`, `put`, `patch`, `delete`, `options` and `trace`\nrespectively. Query parameters can either be provided individually using `queryParam(String, String)` or multiple at \nonce with `queryParams(Multimap\u003cString, String\u003e)`.\n\nThe following operations are applied to URI Templates (`get(String, Object...)`) and URIs (`get(URI)`) respectively:\n\n#### URI Template\n- parameter expansion, e.g `/{id}` (see [`UriTemplate.expand`](http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/util/UriTemplate.html#expand-java.lang.Object...-))\n- encoding\n\n#### URI\n- none, used *as is*\n- expected to be already encoded\n\n#### Both\n- after respective transformation\n- resolved against Base URL (if present)\n- Query String (merged with existing)\n- Normalization\n\nThe [URI Resolution](docs/uri-resolution.md) table shows some examples how URIs are resolved against Base URLs, \nbased on the chosen resolution strategy.\n\nThe `Content-Type`- and `Accept`-header have type-safe methods in addition to the generic support that is\n`header(String, String)` and `headers(HttpHeaders)`.\n\n### Responses\n\nRiptide is special in the way it handles responses. Rather than having a single return value, you need to register\ncallbacks. Traditionally, you would attach different callbacks for different response status codes. Alternatively, there\nare built-in routing capabilities on status code families (called series in Spring) as well as on content types. \n\n```java\nhttp.post(\"/sales-order\")\n    // ...\n    .dispatch(series(),\n        on(SUCCESSFUL).dispatch(contentType(),\n            on(SALES_ORDER).call(SalesOrder.class, this::persist),\n        on(CLIENT_ERROR).dispatch(status(),\n            on(CONFLICT).call(this::retry),\n            on(PRECONDITION_FAILED).call(this::readAgainAndRetry),\n            anyStatus().call(problemHandling())),\n        on(SERVER_ERROR).dispatch(status(),\n            on(SERVICE_UNAVAILABLE).call(this::scheduleRetryLater))));\n```\n\nThe callbacks can have the following signatures:\n\n```java\npersist(SalesOrder)\nretry(ClientHttpResponse)\nscheduleRetryLater()\n```\n\n### Futures\n\nRiptide will return a `CompletableFuture\u003cClientHttpResponse\u003e`. That means you can choose to chain transformations/callbacks or block\non it.\n\nIf you need proper return values take a look at [Riptide: Capture](riptide-capture).\n\n### Exceptions\n\nThe only special custom exception you may receive is `UnexpectedResponseException`, if and only if there was no matching condition and\nno wildcard condition.\n\n### Plugins\n\nRiptide comes with a way to register extensions in the form of plugins.\n\n- `OriginalStackTracePlugin`, preserves stack traces when executing requests asynchronously\n- [`AuthorizationPlugin`](#riptide-auth), adds `Authorization` support\n- [`FailsafePlugin`](riptide-failsafe), adds retries, circuit breaker, backup requests and timeout support\n- [`MicrometerPlugin`](riptide-micrometer), adds metrics for request duration\n- [`TransientFaults`](riptide-faults), detects transient faults, e.g. network issues\n\nWhenever you encounter the need to perform some repetitive task on the futures returned by a remote call,\nyou may consider implementing a custom Plugin for it.\n\nPlugins are executed in phases:\n\n[![Plugin phases](https://docs.google.com/drawings/d/e/2PACX-1vQr2WAQyNILt-UdaCL-2KbBk1QgR2MrpagpnEdI8OjD9l5aopRw2AeM7bg32feN4tutll4DAbYidjn2/pub?w=367\u0026h=659)](https://docs.google.com/drawings/d/1zJC6533at3XzHvxsoUUqyyd4G8cZxmlJ9HFxfhBEcbg/edit?usp=sharing)\n\nPlease consult the [Plugin documentation](riptide-core/src/main/java/org/zalando/riptide/Plugin.java) for details.\n\n### Testing\n\nRiptide is built on the same foundation as Spring's `RestTemplate`. That allows us, with a small\ntrick, to use the same testing facilities, the [`MockRestServiceServer`](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/test/web/client/MockRestServiceServer.html):\n\n```java\nRestTemplate template = new RestTemplate();\nMockRestServiceServer server = MockRestServiceServer.createServer(template);\nClientHttpRequestFactory requestFactory = template.getRequestFactory();\n\nHttp.builder()\n    .requestFactory(requestFactory)\n    // continue configuration\n```\n\nWe basically use an intermediate `RestTemplate` as a holder of the special `ClientHttpRequestFactory` that the\n`MockRestServiceServer` manages.\n\nIf you are using [Spring Boot Starter](riptide-spring-boot-starter), the test setup is provided by a convenient annotation `@RiptideClientTest`. \nSee [here](riptide-spring-boot-starter#testing).\n\n## Getting help\n\nIf you have questions, concerns, bug reports, etc., please file an issue in this repository's [Issue Tracker](issues).\n\n## Getting involved/Contributing\n\nTo contribute, simply make a pull request and add a brief description (1-2 sentences) of your addition or change.\nFor more details check the [contribution guidelines](.github/CONTRIBUTING.md).\n\n## Credits and references\n\n- [URL routing](https://littledev.nl/blog/2015-01-13-url-routing/)\n","funding_links":[],"categories":["Projects","项目","网络编程","Networking"],"sub_categories":["HTTP Clients","HTTP客户端"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzalando%2Friptide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzalando%2Friptide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzalando%2Friptide/lists"}