diff --git a/CHANGELOG.md b/CHANGELOG.md
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,20 @@
# Changelog
+## 1.1.0.0
+
+* **Breaking**: the compressor modules moved to add-on packages so that the
+ core `datastar-hs` has no system-library dependencies.
+ GHC builds it.
+ * `Hypermedia.Datastar.Compression.Zlib` (`gzip`, `deflate`) →
+ [`datastar-hs-zlib`](https://hackage.haskell.org/package/datastar-hs-zlib)
+ * `Hypermedia.Datastar.Compression.Brotli` (`brotli`) →
+ [`datastar-hs-brotli`](https://hackage.haskell.org/package/datastar-hs-brotli)
+ * `Hypermedia.Datastar.Compression.Zstd` (`zstd`) → `datastar-hs-zstd`
+ (not yet on Hackage; the `zstd` cabal flag is gone — build the add-on
+ from this repository instead)
+* `Compressor`, `CompressionStrategy`, `sseResponseWith`, and
+ `sseResponseWithStrategy` are unchanged and stay in the core.
+
## 1.0.2.1
* Fix the `zstd` ratio in the `compression-bench` output (it reported brotli's
diff --git a/README.md b/README.md
--- a/README.md
+++ b/README.md
@@ -21,8 +21,11 @@
Key design decisions:
-- **Minimal dependencies** -- the library depends only on `aeson`, `bytestring`,
-`http-types`, `text`, `wai`, and some compression libraries.
+- **No system libraries** -- the core library depends only on `aeson`,
+`bytestring`, `http-types`, `text`, and `wai`. A machine with just GHC (e.g. a
+fresh [ghcup](https://www.haskell.org/ghcup/) install) builds it; no
+`apt-get`/`brew` needed. Compressors that link against C libraries live in
+add-on packages (see [Compression](#compression)).
- **WAI streaming** -- SSE responses use WAI's native `responseStream`, giving
you a `ServerSentEventGenerator` callback with `sendPatchElements`,
`sendPatchSignals`, and `sendExecuteScript`.
@@ -73,16 +76,23 @@
## Compression
SSE streams can be compressed by negotiating `Content-Encoding` against the
-request's `Accept-Encoding`. Pass one or more compressors to `sseResponseWith`
+request's `Accept-Encoding`. The compressors live in add-on packages so that
+the core `datastar-hs` has no system-library dependencies:
+
+| Package | Encodings | System library |
+|---|---|---|
+| `datastar-hs-zlib` | `gzip`, `deflate` | zlib -- preinstalled on macOS; `zlib1g-dev` on Debian/Ubuntu, or build with the constraint `zlib +bundled-c-zlib` for no system library at all |
+| `datastar-hs-brotli` | `br` | `brew install brotli` / `apt-get install libbrotli-dev pkg-config` |
+| `datastar-hs-zstd` | `zstd` | `brew install zstd` / `apt-get install libzstd-dev` -- not yet on Hackage, see below |
+
+Add one to `build-depends` and pass its compressors to `sseResponseWith`
(or `sseResponseWithStrategy`) in preference order:
```haskell
import Hypermedia.Datastar
-import Hypermedia.Datastar.Compression.Brotli (brotli)
-import Hypermedia.Datastar.Compression.Zlib (deflate, gzip)
-import Hypermedia.Datastar.Compression.Zstd (zstd)
+import Hypermedia.Datastar.Compression.Zlib (deflate, gzip) -- datastar-hs-zlib
-respond $ sseResponseWith nullLogger [brotli, gzip, deflate] req $ \gen ->
+respond $ sseResponseWith nullLogger [gzip, deflate] req $ \gen ->
sendPatchElements gen (patchElements "
Hello!
")
```
diff --git a/bench/Main.hs b/bench/Main.hs
deleted file mode 100644
--- a/bench/Main.hs
+++ /dev/null
@@ -1,122 +0,0 @@
-{-# LANGUAGE CPP #-}
-
-{- |
-A size benchmark for Datastar SSE compression.
-
-It sends one @PatchElements@ event per "tick" over a single SSE connection and
-measures the total bytes that go on the wire, uncompressed vs. gzip vs. brotli —
-using the real SDK compressors and streaming path.
-
-Run: @cabal run bench -- [numEvents] [tableRows]@ (defaults: 400 events, 2000 rows).
--}
-module Main (main) where
-
-import Control.Concurrent.MVar
-import Control.Monad
-import Data.ByteString.Builder qualified as BSB
-import Data.ByteString.Lazy qualified as BL
-import Data.Text (Text)
-import Data.Text qualified as T
-import System.Environment (getArgs)
-import Text.Printf (printf)
-
-import Network.Wai (defaultRequest)
-import Network.Wai.Internal (Response (..))
-
-import Hypermedia.Datastar
-import Hypermedia.Datastar.Compression.Brotli (brotli)
-import Hypermedia.Datastar.Compression.Zlib (gzip)
-#ifdef ZSTD
-import Hypermedia.Datastar.Compression.Zstd (zstd)
-#endif
-
-wireBytes :: Response -> IO Int
-wireBytes (ResponseStream _ _ body) = do
- nrBytes <- newMVar 0
-
- let chunkLen = fromIntegral . BL.length . BSB.toLazyByteString
-
- body
- (\chunk -> modifyMVar_ nrBytes $ \nr -> return $ nr + chunkLen chunk)
- (pure ())
-
- readMVar nrBytes
-
-wireBytes _ = error "expected a streaming response"
-
-sendAll :: [Text] -> ServerSentEventGenerator -> IO ()
-sendAll frags gen = forM_ frags (sendPatchElements gen . patchElements)
-
-rawBytes :: [Text] -> IO Int
-rawBytes frags = wireBytes (sseResponse nullLogger (sendAll frags))
-
-compressedBytes :: Compressor -> [Text] -> IO Int
-compressedBytes c frags =
- wireBytes (sseResponseWithStrategy Forced nullLogger [c] defaultRequest (sendAll frags))
-
-bench :: String -> [Text] -> IO ()
-bench name frags = do
- let n = length frags
- perEvent = if n == 0 then 0 else T.length (head frags)
- rawN <- rawBytes frags
- gzN <- compressedBytes gzip frags
- brN <- compressedBytes brotli frags
-
- printf "\n=== %s ===\n" name
- printf " %d events, ~%s uncompressed per fragment\n\n" n (human perEvent)
- printf " none : %12s\n" (human rawN)
- printf " gzip : %12s (%7.1fx vs none)\n" (human gzN) (ratio rawN gzN)
- printf " brotli : %12s (%7.1fx vs none)\n" (human brN) (ratio rawN brN)
-#ifdef ZSTD
- zstdN <- compressedBytes zstd frags
- printf " zstd : %12s (%7.1fx vs none)\n" (human zstdN) (ratio rawN zstdN)
-#endif
-
-ratio :: Int -> Int -> Double
-ratio a b = if b == 0 then 0 else fromIntegral a / fromIntegral b
-
-human :: Int -> String
-human n
- | n >= 1024 * 1024 = printf "%.1f MB" (fromIntegral n / (1024 * 1024) :: Double)
- | n >= 1024 = printf "%.1f KB" (fromIntegral n / 1024 :: Double)
- | otherwise = printf "%d B" n
-
-tshow :: Int -> Text
-tshow = T.pack . show
-
--- A self-similar table row (lots of intra-fragment repetition).
-gridRow :: Int -> Text
-gridRow i =
- "
" <> tshow i <> "
item-" <> tshow i <> "
active
0.00
"
-
--- A large grid (>32 KB for a couple thousand rows), optionally stamped with a
--- per-tick caption so only a tiny part changes between events.
-grid :: Int -> Maybe Int -> Text
-grid rows mtick =
- "
\n\n")
- flush
- afterSecond <- sizeSoFar
-
- finish
- afterFinish <- sizeSoFar
-
- -- Each flush must push bytes onto the wire; a compressor that buffered
- -- everything until finish would leave afterFirst == afterSecond == 0.
- afterFirst `shouldSatisfy` (> (0 :: Int))
- afterSecond `shouldSatisfy` (> afterFirst)
- afterFinish `shouldSatisfy` (>= afterSecond)
-
- whole <- BSB.toLazyByteString <$> readIORef ref
- Zstd.decompress whole
- `shouldBe` "event: datastar-patch-elements\ndata: elements
1
\n\n\
- \event: datastar-patch-elements\ndata: elements
2
\n\n"
diff --git a/test/Hypermedia/Datastar/NegotiationSpec.hs b/test/Hypermedia/Datastar/NegotiationSpec.hs
new file mode 100644
--- /dev/null
+++ b/test/Hypermedia/Datastar/NegotiationSpec.hs
@@ -0,0 +1,41 @@
+module Hypermedia.Datastar.NegotiationSpec (spec) where
+
+import Test.Hspec
+
+import Data.ByteString.Lazy qualified as BL
+
+import Network.Wai (defaultRequest, requestHeaders)
+
+import Hypermedia.Datastar
+import Hypermedia.Datastar.WAI (Compressor (..), negotiateWith)
+
+{- | A compressor that only carries an encoding token, for negotiation tests.
+Its 'compressorWrap' is never invoked by 'negotiateWith'.
+-}
+fakeCompressor :: BL.ByteString -> Compressor
+fakeCompressor enc = Compressor (BL.toStrict enc) (\_ _ -> error "unused")
+
+spec :: Spec
+spec = describe "negotiateWith" $ do
+ let br = fakeCompressor "br"
+ gz = fakeCompressor "gzip"
+ enc = fmap compressorEncoding
+ req h = defaultRequest{requestHeaders = [("Accept-Encoding", h)]}
+
+ it "ServerPriority picks the first server compressor the client accepts" $
+ enc (negotiateWith ServerPriority [br, gz] (req "gzip, br")) `shouldBe` Just "br"
+
+ it "ClientPriority picks the client's most-preferred offered encoding" $
+ enc (negotiateWith ClientPriority [br, gz] (req "gzip, br")) `shouldBe` Just "gzip"
+
+ it "Forced ignores Accept-Encoding entirely" $
+ enc (negotiateWith Forced [br, gz] (req "identity")) `shouldBe` Just "br"
+
+ it "ignores q-value params and whitespace around each token" $
+ enc (negotiateWith ClientPriority [br, gz] (req " gzip;q=0.1 , br ")) `shouldBe` Just "gzip"
+
+ it "returns Nothing when no server encoding is accepted" $
+ enc (negotiateWith ServerPriority [br, gz] (req "deflate")) `shouldBe` Nothing
+
+ it "returns Nothing when the Accept-Encoding header is absent" $
+ enc (negotiateWith ServerPriority [br, gz] defaultRequest) `shouldBe` Nothing
diff --git a/test/Hypermedia/Datastar/PatchElementsSpec.hs b/test/Hypermedia/Datastar/PatchElementsSpec.hs
--- a/test/Hypermedia/Datastar/PatchElementsSpec.hs
+++ b/test/Hypermedia/Datastar/PatchElementsSpec.hs
@@ -82,22 +82,22 @@
]
it "omits namespace when html (default)" $ do
- let lines =
+ let lines' =
dataLines $
toDatastarEvent $
patchElements "
hello
"
- any (T.isPrefixOf "namespace") lines `shouldBe` False
+ any (T.isPrefixOf "namespace") lines' `shouldBe` False
it "omits mode when Outer (default)" $ do
let pe = patchElements "