-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
10 changed files
with
183 additions
and
39 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,13 @@ | ||
--- | ||
layout: doc-page | ||
title: "A Production Ready Example" | ||
--- | ||
In the section, I'll walk you through the Http4s' jokes service that generated by `sbt new http4s/http4s.g8`, but production ready. By production ready, I mean it is ready to ship and your have all the observability. | ||
|
||
You can generate the example project by running | ||
|
||
``` | ||
sbt new jcouyang/http4s.g8 | ||
``` | ||
|
||
## TODO |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,44 @@ | ||
--- | ||
layout: doc-page | ||
title: "Why Finagle x Http4s?" | ||
--- | ||
|
||
Finagle is an extensible RPC system that Twitter running on, there are bunch of | ||
production ready things to use, without needing particular setup, batteries included such as: | ||
|
||
## Zipkin distributed tracing | ||
So if all your microservices are running on Finagle, it is pretty much 0 config to get Zipkin | ||
just works. | ||
![](https://zipkin.io/public/img/web-screenshot.png) | ||
you can query a request's journey through all your microservices by just query it's trace id, | ||
interesting data will be summarized for you, such as the percentage of time spent in which service, and whether or not operations failed. | ||
|
||
## Metrics | ||
Finagle will automatically generate [metrics](https://twitter.github.io/finagle/guide/Metrics.html) for server and client when you enable them with | ||
```scala | ||
.withHttpStats | ||
``` | ||
There are some adapter ready to use to expose to different format, such as [Prometheus](https://samstarling.co.uk/projects/finagle-prometheus/) | ||
|
||
## Circuit Breaker x Load Balancer x Retry | ||
- [Circuit Breaker](https://twitter.github.io/finagle/guide/Clients.html#circuit-breaking) | ||
- [Load Balancer](https://twitter.github.io/finagle/guide/ApertureLoadBalancers.html) | ||
- [Retry](https://twitter.github.io/finagle/guide/Clients.html#retries) | ||
|
||
Since Finagle is RPC system, it is very easy to detect error accurately, you can also apply [custom | ||
classifier](https://twitter.github.io/finagle/guide/Clients.html#custom-classifiers) to identity different kinds of error | ||
|
||
## Twitter Server | ||
If we run Finagle Service on a [Twitter Server](https://twitter.github.io/twitter-server/), then we will get | ||
|
||
- Logging with dynamo log level control | ||
- flag and feature toggle | ||
- a Admin portal that can monitor metrics and histograms | ||
|
||
## Finagle x Http4s | ||
|
||
The pain point is when there are lot of existing Finagle RPC services running on production already, and | ||
when I introduced Http4s service, I need to spend too many time to make Zipkin, metrics, circuit breaker work the | ||
same way with the existing services, but if I give up new service will be couple with Finagle/Finatra dsl forever. | ||
|
||
Now with http4s-finagle, we can actually take advantage of both, create business with Http4s, and run them on Finagle to keep Devops practice consistent. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
--- | ||
layout: doc-page | ||
title: "Http4s Finagle" | ||
--- | ||
|
||
Table of Contents | ||
================= | ||
{% assign titles = sidebar.titles %} | ||
<ul> | ||
{% for item in titles %} | ||
<li> | ||
{% if item.url %} | ||
<a href="{{ site.baseurl }}/{{ item.url }}">{{ item.title }}</a> | ||
{% else %} | ||
{{ item.title }} | ||
{% endif %} | ||
</li> | ||
{% endfor %} | ||
</ul> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,24 @@ | ||
--- | ||
layout: doc-page | ||
title: "Installation" | ||
--- | ||
|
||
The latest version currently is | ||
[![](https://index.scala-lang.org/http4s/http4s-finagle/latest.svg?v=1)](https://index.scala-lang.org/http4s/http4s-finagle) | ||
|
||
http4s-finagle is available for Scala 2.12, 2.13 and dotty, please refer to https://index.scala-lang.org/http4s/http4s-finagle for detail. | ||
|
||
In general if your `http4s` version is `0.21.6` | ||
simply set `http4s-finagle` to `0.21.6+` | ||
```scala | ||
libraryDependencies += "org.http4s" %% "http4s-finagle" % "0.21.6+" | ||
``` | ||
|
||
http4s-finagle version is a combination of both version of http4s and finagle, finagle is pretty stable and monthly release, | ||
so you probably don't want to fix the finagle version. | ||
|
||
``` | ||
libraryDependencies += "org.http4s" %% "http4s-finagle" % "0.21.4-20.4.1-0" | ||
^ ^ ^ | ||
http4s fingale patch | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,50 @@ | ||
--- | ||
layout: doc-page | ||
title: "Quick Started" | ||
--- | ||
|
||
## Server | ||
|
||
To run Http4s app on Finagle Http server, simply just use `Finagle.mkService` to adapt Http4s `HttpApp[F]` to Fingale `Service[Request, Response]`. | ||
|
||
```scala | ||
import org.http4s.finagle._ | ||
import com.twitter.finagle.Http | ||
|
||
val http4sService: HttpApp[IO] = HttpRoutes.of[IO] {...}.orNotFound | ||
|
||
val server = Http.server.serve(":8080", Finagle.mkService(http4sService)) | ||
Await.ready(server) | ||
``` | ||
|
||
## Client | ||
To make a Finagle Client is the other way around, we need to adapt Finagle `Service[Request, Response]` to Http4s `Client[IO]`: | ||
|
||
```scala | ||
import org.http4s.finagle._ | ||
import com.twitter.finagle.Http | ||
|
||
val host = "blog.oyanglul.us" | ||
Finagle.mkClient[IO](Http.client.withTls(host).newService(s"$host:443")).use { | ||
client: Client[IO] => | ||
... | ||
} | ||
``` | ||
|
||
### :warning: | ||
A fundamental different from usual Http client is that finagle `Client[IO]` is actually a RPC Http client, | ||
which means it cannot send arbitrary request to any host, the host endpoint is already set when created | ||
this client. This machinism is very useful to identify endpoint healthy, load balancer, circuit breaker. | ||
But a little bit weird when using: | ||
|
||
```scala | ||
val host = "blog.oyanglul.us" | ||
Finagle.mkClient[IO](Http.client.withTls(host).newService(s"$host:443")).use { | ||
client: Client[IO] => | ||
client.status(uri"https://twiter.com") | ||
client.status(uri"https://abc.com/blahblah") | ||
} | ||
``` | ||
|
||
- `client.status(uri"https://twiter.com")` will still send request to `https://blog.oyanglul.us` | ||
- `client.status(uri"https://abc.com/blahblah")` will send request to `https://blog.oyanglul.us/blahblah` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
sidebar: | ||
- title: Installation | ||
url: docs/install.html | ||
- title: Quick Start | ||
url: docs/quick-start.html | ||
- title: Why Finagle? | ||
url: docs/finagle.html | ||
- title: Production Ready Example | ||
url: docs/example.html |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,12 @@ | ||
#!/bin/bash | ||
sbt "++0.25.0;clean;doc" | ||
egrep -rl 'html' docs/_site/api | xargs -I@ sed -i '' 's/"\/docs/"\/http4s-finagle\/docs/g' @ | ||
egrep -rl 'html' docs/_site/api | xargs -I@ sed -i '' 's/"\/api/"\/http4s-finagle\/api/g' @ | ||
egrep -rl 'html' docs/_site/api | xargs -I@ sed -i '' 's/"\/images/"\/http4s-finagle\/images/g' @ | ||
egrep -rl 'html' docs/_site/api | xargs -I@ sed -i '' 's/"\/js/"\/http4s-finagle\/js/g' @ | ||
egrep -rl 'html' docs/_site/api | xargs -I@ sed -i '' 's/"\/css/"\/http4s-finagle\/css/g' @ | ||
egrep -rl 'html' docs/_site/docs | xargs -I@ sed -i '' 's/"\/docs/"\/http4s-finagle\/docs/g' @ | ||
egrep -rl 'html' docs/_site/docs | xargs -I@ sed -i '' 's/"\/api/"\/http4s-finagle\/api/g' @ | ||
egrep -rl 'html' docs/_site/docs | xargs -I@ sed -i '' 's/"\/images/"\/http4s-finagle\/images/g' @ | ||
egrep -rl 'html' docs/_site/docs | xargs -I@ sed -i '' 's/"\/js/"\/http4s-finagle\/js/g' @ | ||
egrep -rl 'html' docs/_site/docs | xargs -I@ sed -i '' 's/"\/css/"\/http4s-finagle\/css/g' @ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -126,4 +126,4 @@ object Finagle { | |
.unsafeRunSync() | ||
promise | ||
} | ||
} | ||
} |