HTTP Support from Protocols

[juanpedromoreno]

frees-rpc is for RPC.

Having said that, it'd be great supporting the creation of HTTP/REST endpoints taking advantage of the RPC service implementations. This is mandatory in some cases/environments when the HTTP/REST API is the only way possible.

This is related to #73, but focuses on the scenario of HTTP/REST on both ends instead of a REST<->gRPC converter or proxy.

Subtasks:

• Naming. A module named frees-rpc-http is implemented in Hello, Http Server integration #203. Ideally we'll want to settle on a naming convention for the feature such as HTTP, REST or HTTP/REST.
• Transport Implementation
  • Transport/Framework layer implementation. Our current approach is to use http4s and its DSL, as implemented here.
  • FS2 streaming support. Supported by http4s, mainly for server-streaming but client/bidi streaming is also possible, and implemented here.
  • Monix/Observable streaming support. Reversing the gRPC-based approach in the main project, we can convert FS2 to Monix internally, as implemented here.
  • Error handling. Just as with RPC, we'll want to support error raising in monadic (MonadError) and streaming contexts (keeping in mind that a stream can start OK and end in error). The sample implementation here accepts gRPC's thrown Status[Runtime]Exception for triggering specific return codes, but we'll probably want to provide a more generic type of error for this.
  • HTTP/2 support: Http4s supports this on the server side (requires TLS) but the state of client-side support is less clear. This is tracked in HTTP Support from Protocols - Http2 Spike #205.
• Endpoint Derivation
  • Annotations/DSL to define HTTP endpoints and registering the different routes; there are some ideas in gRPC-web protocol wrapper/proxy #73. In any case, we'll need macro support to process them for server/client derivation, and we're holding off on macro-based development until we've decided on a new codegen system for freestyle[-rpc], as discussed in SPIKE: Replacements for scalameta-based macros frees-io/freestyle#539.
  • Http Server Derivation. By processing the annotations we'll want to end up with something like this.
  • Http Client Derivation. As above, for something like this. Work being done in WIP: derive http client from service #368
  • Multi-server bootstrapping. We need to provide utilities and helpers to start/shutdown both server RPC and HTTP servers (obviously on different ports).
• Endpoint Documentation
  • Open API/Swagger. Open-API 3.0 (implemented in Swagger 2.0) seems promising, but the Scala tools to generate it are not ideal currently. Http4s has it in the rho project, but very closely tied to its DSL. Swagger-scala-module supports message classes but not services, and doesn't support Open-API 3 yet (support swagger-core 2.0.0 swagger-api/swagger-scala-module#49). We'll revisit it once it does.

(original text by @juanpedromoreno, last edited by @L-Lavigne)

[juanpedromoreno]

This is probably a bit outdated. Closing it for now.