Servant.API.Stream

servant-0.20.2: A family of combinators for defining webservices APIs

Safe Haskell | None
Language | Haskell2010

Servant.API.Stream

Contents

- Source
  - Auxiliary classes
- Framing
  - Strategies

Synopsis

- data Stream (method :: k1) (status :: Nat) framing contentType a
- type StreamGet = Stream 'GET 200
- type StreamPost = Stream 'POST 200
- type StreamBody = StreamBody' ('[] :: [Type])
- data StreamBody' (mods :: [Type]) framing contentType a
- type SourceIO = SourceT IO
- class ToSourceIO chunk a | a -> chunk where
  - toSourceIO :: a -> SourceIO chunk
- class FromSourceIO chunk a | a -> chunk where
  - fromSourceIO :: SourceIO chunk -> IO a
- class SourceToSourceIO (m :: Type -> Type) where
  - sourceToSourceIO :: SourceT m a -> SourceT IO a
- class FramingRender (strategy :: k) where
  - framingRender :: forall (m :: Type -> Type) a. Monad m => Proxy strategy -> (a -> ByteString) -> SourceT m a -> SourceT m ByteString
- class FramingUnrender (strategy :: k) where
  - framingUnrender :: forall (m :: Type -> Type) a. Monad m => Proxy strategy -> (ByteString -> Either String a) -> SourceT m ByteString -> SourceT m a
- data NoFraming
- data NewlineFraming
- data NetstringFraming

# Documentation

data Stream (method :: k1) (status :: Nat) framing contentType a #

A Stream endpoint for a given method emits a stream of encoded values at a given `Content-Type`, delimited by a `framing` strategy. Type synonyms are provided for standard methods.

#### Instances

Instances details

HasLink (Stream m status fr ct a :: Type) # |
Instance details Defined in Servant.Links Methods toLink :: (Link -> a0) -> Proxy (Stream m status fr ct a) -> Link -> MkLink (Stream m status fr ct a) a0 #
Generic (Stream method status framing contentType a) # |
Instance details Defined in Servant.API.Stream Associated Types
type Rep (Stream method status framing contentType a) |
Instance details Defined in Servant.API.Stream type Rep (Stream method status framing contentType a) = D1 ('MetaData "Stream" "Servant.API.Stream" "servant-0.20.2-9fHyWNA72dIEEHjgDnkpGL" 'False) (V1 :: Type -> Type)
Methods from :: Stream method status framing contentType a -> Rep (Stream method status framing contentType a) x # to :: Rep (Stream method status framing contentType a) x -> Stream method status framing contentType a #
type MkLink (Stream m status fr ct a :: Type) r # |
Instance details Defined in Servant.Links type MkLink (Stream m status fr ct a :: Type) r = r
type Rep (Stream method status framing contentType a) # |
Instance details Defined in Servant.API.Stream type Rep (Stream method status framing contentType a) = D1 ('MetaData "Stream" "Servant.API.Stream" "servant-0.20.2-9fHyWNA72dIEEHjgDnkpGL" 'False) (V1 :: Type -> Type)

type StreamGet = Stream 'GET 200 #

type StreamPost = Stream 'POST 200 #

type StreamBody = StreamBody' ('[] :: [Type]) #

A stream request body.

data StreamBody' (mods :: [Type]) framing contentType a #

#### Instances

Instances details

HasLink sub => HasLink (StreamBody' mods framing ct a :> sub :: Type) # |
Instance details Defined in Servant.Links Methods toLink :: (Link -> a0) -> Proxy (StreamBody' mods framing ct a :> sub) -> Link -> MkLink (StreamBody' mods framing ct a :> sub) a0 #
Generic (StreamBody' mods framing contentType a) # |
Instance details Defined in Servant.API.Stream Associated Types
type Rep (StreamBody' mods framing contentType a) |
Instance details Defined in Servant.API.Stream type Rep (StreamBody' mods framing contentType a) = D1 ('MetaData "StreamBody'" "Servant.API.Stream" "servant-0.20.2-9fHyWNA72dIEEHjgDnkpGL" 'False) (V1 :: Type -> Type)
Methods from :: StreamBody' mods framing contentType a -> Rep (StreamBody' mods framing contentType a) x # to :: Rep (StreamBody' mods framing contentType a) x -> StreamBody' mods framing contentType a #
type MkLink (StreamBody' mods framing ct a :> sub :: Type) r # |
Instance details Defined in Servant.Links type MkLink (StreamBody' mods framing ct a :> sub :: Type) r = MkLink sub r
type Rep (StreamBody' mods framing contentType a) # |
Instance details Defined in Servant.API.Stream type Rep (StreamBody' mods framing contentType a) = D1 ('MetaData "StreamBody'" "Servant.API.Stream" "servant-0.20.2-9fHyWNA72dIEEHjgDnkpGL" 'False) (V1 :: Type -> Type)

# Source

`SourceIO` are equivalent to some *source* in streaming libraries.

type SourceIO = SourceT IO #

Stream endpoints may be implemented as producing a ``SourceIO` chunk`.

Clients reading from streaming endpoints can be implemented as consuming a ``SourceIO` chunk`.

class ToSourceIO chunk a | a -> chunk where #

`ToSourceIO` is intended to be implemented for types such as Conduit, Pipe, etc. By implementing this class, all such streaming abstractions can be used directly as endpoints.

Methods

toSourceIO :: a -> SourceIO chunk #

#### Instances

Instances details

ToSourceIO a (NonEmpty a) # |
Instance details Defined in Servant.API.Stream Methods toSourceIO :: NonEmpty a -> SourceIO a #
ToSourceIO a [a] # |
Instance details Defined in Servant.API.Stream Methods toSourceIO :: [a] -> SourceIO a #
SourceToSourceIO m => ToSourceIO chunk (SourceT m chunk) # | Relax to use auxiliary class, have m
Instance details Defined in Servant.API.Stream Methods toSourceIO :: SourceT m chunk -> SourceIO chunk #

class FromSourceIO chunk a | a -> chunk where #

`FromSourceIO` is intended to be implemented for types such as Conduit, Pipe, etc. By implementing this class, all such streaming abstractions can be used directly on the client side for talking to streaming endpoints.

Methods

fromSourceIO :: SourceIO chunk -> IO a #

#### Instances

Instances details

MonadIO m => FromSourceIO a (SourceT m a) # |
Instance details Defined in Servant.API.Stream Methods fromSourceIO :: SourceIO a -> IO (SourceT m a) #

## Auxiliary classes

class SourceToSourceIO (m :: Type -> Type) where #

Auxiliary class for ``ToSourceIO` x (`SourceT` m x)` instance.

Methods

sourceToSourceIO :: SourceT m a -> SourceT IO a #

#### Instances

Instances details

SourceToSourceIO IO # |
Instance details Defined in Servant.API.Stream Methods sourceToSourceIO :: SourceT IO a -> SourceT IO a #

# Framing

class FramingRender (strategy :: k) where #

The `FramingRender` class provides the logic for emitting a framing strategy. The strategy transforms a ``SourceT` m a` into ``SourceT` m `ByteString``, therefore it can prepend, append and intercalate framing structure around chunks.

Note: as the ``Monad` m` is generic, this is pure transformation.

Methods

framingRender :: forall (m :: Type -> Type) a. Monad m => Proxy strategy -> (a -> ByteString) -> SourceT m a -> SourceT m ByteString #

#### Instances

Instances details

FramingRender NetstringFraming # |
Instance details Defined in Servant.API.Stream Methods framingRender :: forall (m :: Type -> Type) a. Monad m => Proxy NetstringFraming -> (a -> ByteString) -> SourceT m a -> SourceT m ByteString #
FramingRender NewlineFraming # |
Instance details Defined in Servant.API.Stream Methods framingRender :: forall (m :: Type -> Type) a. Monad m => Proxy NewlineFraming -> (a -> ByteString) -> SourceT m a -> SourceT m ByteString #
FramingRender NoFraming # |
Instance details Defined in Servant.API.Stream Methods framingRender :: forall (m :: Type -> Type) a. Monad m => Proxy NoFraming -> (a -> ByteString) -> SourceT m a -> SourceT m ByteString #

class FramingUnrender (strategy :: k) where #

The `FramingUnrender` class provides the logic for parsing a framing strategy.

Methods

framingUnrender :: forall (m :: Type -> Type) a. Monad m => Proxy strategy -> (ByteString -> Either String a) -> SourceT m ByteString -> SourceT m a #

#### Instances

Instances details

FramingUnrender NetstringFraming # |
Instance details Defined in Servant.API.Stream Methods framingUnrender :: forall (m :: Type -> Type) a. Monad m => Proxy NetstringFraming -> (ByteString -> Either String a) -> SourceT m ByteString -> SourceT m a #
FramingUnrender NewlineFraming # |
Instance details Defined in Servant.API.Stream Methods framingUnrender :: forall (m :: Type -> Type) a. Monad m => Proxy NewlineFraming -> (ByteString -> Either String a) -> SourceT m ByteString -> SourceT m a #
FramingUnrender NoFraming # | As `NoFraming` doesn't have frame separators, we take the chunks as given and try to convert them one by one. That works well when `a` is a `ByteString`.
Instance details Defined in Servant.API.Stream Methods framingUnrender :: forall (m :: Type -> Type) a. Monad m => Proxy NoFraming -> (ByteString -> Either String a) -> SourceT m ByteString -> SourceT m a #

## Strategies

data NoFraming #

A framing strategy that does not do any framing at all, it just passes the input data This will be used most of the time with binary data, such as files

#### Instances

Instances details

FramingRender NoFraming # |
Instance details Defined in Servant.API.Stream Methods framingRender :: forall (m :: Type -> Type) a. Monad m => Proxy NoFraming -> (a -> ByteString) -> SourceT m a -> SourceT m ByteString #
FramingUnrender NoFraming # | As `NoFraming` doesn't have frame separators, we take the chunks as given and try to convert them one by one. That works well when `a` is a `ByteString`.
Instance details Defined in Servant.API.Stream Methods framingUnrender :: forall (m :: Type -> Type) a. Monad m => Proxy NoFraming -> (ByteString -> Either String a) -> SourceT m ByteString -> SourceT m a #

data NewlineFraming #

A simple framing strategy that has no header, and inserts a newline character after each frame. This assumes that it is used with a Content-Type that encodes without newlines (e.g. JSON).

#### Instances

Instances details

FramingRender NewlineFraming # |
Instance details Defined in Servant.API.Stream Methods framingRender :: forall (m :: Type -> Type) a. Monad m => Proxy NewlineFraming -> (a -> ByteString) -> SourceT m a -> SourceT m ByteString #
FramingUnrender NewlineFraming # |
Instance details Defined in Servant.API.Stream Methods framingUnrender :: forall (m :: Type -> Type) a. Monad m => Proxy NewlineFraming -> (ByteString -> Either String a) -> SourceT m ByteString -> SourceT m a #

data NetstringFraming #

The netstring framing strategy as defined by djb: http://cr.yp.to/proto/netstrings.txt

Any string of 8-bit bytes may be encoded as `[len]":"[string]","`. Here `[string]` is the string and `[len]` is a nonempty sequence of ASCII digits giving the length of `[string]` in decimal. The ASCII digits are `30` for 0, `31` for 1, and so on up through `39` for 9. Extra zeros at the front of `[len]` are prohibited: `[len]` begins with `30` exactly when `[string]` is empty.

For example, the string `"hello world!"` is encoded as `32 3a 68 65 6c 6c 6f 20 77 6f 72 6c 64 21 2c`, i.e., `"12:hello world!,"`. The empty string is encoded as `"0:,"`.

#### Instances

Instances details

FramingRender NetstringFraming # |
Instance details Defined in Servant.API.Stream Methods framingRender :: forall (m :: Type -> Type) a. Monad m => Proxy NetstringFraming -> (a -> ByteString) -> SourceT m a -> SourceT m ByteString #
FramingUnrender NetstringFraming # |
Instance details Defined in Servant.API.Stream Methods framingUnrender :: forall (m :: Type -> Type) a. Monad m => Proxy NetstringFraming -> (ByteString -> Either String a) -> SourceT m ByteString -> SourceT m a #