Merge pull request #2 from avanov/master

A few clarifying comments and a slight change in module arrangement

.gitignore

@@ -1,4 +1,6 @@
 dist/
 dist-newstyle/
 .ghc.environment.*
-.stack-work/
+.stack-work/
+# nix results
+result

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Revision history for servant-event-stream
 
+## 0.2.0.0 -- 2021-04-x
+
+* `Servant.EventStream` was moved to `Servant.API.EventStream` to adhere existing [upstream layout](https://hackage.haskell.org/package/servant-0.18.2/docs/Servant-API-Stream.html).
+
 ## 0.1.0.0 -- 2018-04-30
 
 * First version. Released on an unsuspecting world.

README.md

@@ -0,0 +1,21 @@
+servant-event-stream
+====================
+
+This library adds necessary type combinators to support [Server Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)
+within [Servant ecosystem](https://github.com/haskell-servant/).
+
+Dev Environment
+---------------
+
+Dev env is based on [Nix](https://nixos.org) and [Niv](https://github.com/nmattia/niv).
+
+To enter the dev shell, run
+```bash
+
+nix-shell
+```
+
+You can build the project with
+```bash
+nix-build
+```

servant-event-stream.cabal

@@ -1,6 +1,6 @@
 cabal-version:       >=1.10
 name:                servant-event-stream
-version:             0.1.0.0
+version:             0.2.0.0
 stability:           alpha
 
 synopsis:            Servant support for Server-Sent events
@@ -26,7 +26,7 @@ source-repository head
 
 library
   exposed-modules:
-    Servant.EventStream
+    Servant.API.EventStream
 
   default-extensions:
     MultiParamTypeClasses
@@ -48,3 +48,11 @@ library
   hs-source-dirs:      src
   default-language:    Haskell2010
   ghc-options:         -Wall
+
+test-suite tests-default
+  type: exitcode-stdio-1.0
+  main-is: Spec.hs
+  hs-source-dirs:
+    tests
+  build-depends:
+    base

src/Servant/EventStream.hs → src/Servant/API/EventStream.hs

@@ -8,7 +8,7 @@
 {-# LANGUAGE TypeFamilies               #-}
 {-# LANGUAGE UndecidableInstances       #-}
 
-module Servant.EventStream
+module Servant.API.EventStream
   ( ServerSentEvents
   , EventStream
   , EventSource
@@ -52,6 +52,7 @@ instance HasServer ServerSentEvents context where
   hoistServerWithContext Proxy = hoistServerWithContext
     (Proxy :: Proxy (StreamGet NoFraming EventStream EventSourceHdr))
 
+-- | a helper instance for <https://hackage.haskell.org/package/servant-foreign-0.15.3/docs/Servant-Foreign.html servant-foreign>
 instance  (HasForeignType lang ftype EventSourceHdr)
   => HasForeign lang ftype ServerSentEvents where
   type Foreign ftype ServerSentEvents = Req ftype
@@ -65,15 +66,22 @@ instance  (HasForeignType lang ftype EventSourceHdr)
     retType = typeFor lang (Proxy :: Proxy ftype) (Proxy :: Proxy EventSourceHdr)
     method  = reflectMethod (Proxy :: Proxy 'GET)
 
+-- | A type representation of an event stream. It's responsible for setting proper content-type
+--   and buffering headers, as well as for providing parser implementations for the streams.
+--   Read more on <https://docs.servant.dev/en/stable/tutorial/Server.html#streaming-endpoints Servant Streaming Docs>
 data EventStream
 
 instance Accept EventStream where
   contentType _ = "text" // "event-stream" /: ("charset", "utf-8")
 
 type EventSource = SourceIO ServerEvent
 
+-- | This is mostly to guide reverse-proxies like 
+--   <https://www.nginx.com/resources/wiki/start/topics/examples/x-accel/#x-accel-buffering nginx>
 type EventSourceHdr = Headers '[Header "X-Accel-Buffering" Text] EventSource
 
+-- | See details at
+--   https://hackage.haskell.org/package/wai-extra-3.1.6/docs/Network-Wai-EventSource-EventStream.html#v:eventToBuilder
 instance MimeRender EventStream ServerEvent where
   mimeRender _ = maybe "" toLazyByteString . eventToBuilder
 

tests/Spec.hs

@@ -0,0 +1,2 @@
+main :: IO ()
+main = putStrLn "Test suite not yet implemented"