HTTP Streaming

Finatra supports streaming over HTTP with a StreamingRequest or a StreamingResponse. A StreamingRequest/StreamingResponse is an HTTP Request/Response that carries a stream of objects in its body (preferably in the form of Reader, or AsyncStream). You can create and access the stream via request.stream or response.stream.

Advantages

The major advantages of Finatra HTTP Streaming include:

• Ability to stream at object level instead of bytes.
  • StreamingResponse will serialize a Json object to a Json string with its ObjectMapper.
  • StreamingRequest will deserialize a valid Json string to a Json object with its JsonStreamParser.
• Resource management by listening to the result from Reader#onClose.
• Easy manipulation of each stream chunk via Reader#map.
• Built-in streaming metrics to gain more insights into streams’ health.

Example

• How to stream from your controller:

import com.twitter.finatra.http.streaming.StreamingRequest
import com.twitter.io.Reader

post("/tweets/streaming/reader") { streamingRequest: StreamingRequest[Reader, Tweet] =>
  // create a `Reader` with any object types to pass to the `StreamingResponse`
  val responseReader: Reader[String] = streamingRequest.stream.map(_.text)
  // create a `StreamingResponse` via `ResponseBuilder`
  response.streaming(responseReader)
}

• How to stream with resource management:

import com.twitter.finatra.http.streaming.StreamingRequest
import com.twitter.io.Reader
import com.twitter.util.Closable

post("/tweets/streaming/reader_with_resource_management") {
  streamingRequest: StreamingRequest[Reader, Tweet] =>
  // A closable resource that needs to listen to the close of the stream
  val closable = Closable.nop
  // create a `Reader` with any object types to pass to the `StreamingResponse`
  val responseReader: Reader[String] = streamingRequest.stream.map(_.text)
  // close the resource after `reader#onClose` is resolved
  responseReader.onClose.ensure(closable.close())
  // create a `StreamingResponse` via `ResponseBuilder`
  response.streaming(responseReader)
}

You can check out more streaming examples from Finatra examples.