1.2.1 Server Setup🔗ℹ

Use dispatch/servlet from web-server/servlet-dispatch to convert your servlet into a dispatcher, then choose a serve configuration that matches your stream behavior.

Decision guide

• Short-lived SSE (send one/few events, then return): defaults usually work; these transport knobs are optional.

• Long-lived or mostly idle streams (subscriptions, optional CQRS read-model updates): configure #:safety-limits so response timeouts do not terminate idle handlers (for example, +inf.0, or periodic chunks/heartbeats).

• Blocked on-open loop + prompt disconnect cleanup: use both #:connection-close? #t and #:tcp@ datastar-tcp@.

Minimal setup

(serve #:dispatch (dispatch/servlet handler))

Robust setup (long-lived streams / prompt blocked-loop disconnect cleanup)

(serve #:dispatch (dispatch/servlet handler)

#:tcp@ datastar-tcp@

#:connection-close? #t

#:safety-limits (make-safety-limits #:response-timeout +inf.0

#:response-send-timeout +inf.0))

When provided, datastar-sse monitors the underlying TCP input port and interrupts on-open when the client disconnects, so on-close can run sooner.

1.2.2 SSE Generator🔗ℹ

Create SSE responses and send events through an sse? generator.

Configure serve using Server Setup: minimal setup for short-lived streams, robust setup for long-lived streams or fast disconnect handling.

1.2.3 Locking🔗ℹ

Coordinate concurrent senders with explicit SSE locking. All send functions are thread-safe: multiple threads can send events through the same generator and delivery order is serialized. If multiple threads share a single generator, use with-sse-lock to send a group of events without interleaving.

Use this only when multiple threads send through the same sse? generator. If each generator is used by a single thread (the common case), individual sends are already thread-safe and this locking is unnecessary.

The lock is re-entrant: all send functions (patch-elements, patch-signals, etc.) use call-with-sse-lock internally, so calling them inside a locked region does not deadlock.

(call-with-sse-lock sse

(lambda ()

(patch-elements/xexprs sse '(div ((id "a")) "part 1"))

(patch-elements/xexprs sse '(div ((id "b")) "part 2"))

(patch-signals sse (hash 'status "updated"))))

If an exception is raised inside thunk, the lock is released via dynamic-wind, so subsequent sends can still proceed.

(with-sse-lock sse

(patch-elements/xexprs sse '(div ((id "a")) "part 1"))

(patch-elements/xexprs sse '(div ((id "b")) "part 2"))

(patch-signals sse (hash 'status "updated")))

1.2.4 Signals🔗ℹ

Send signal patch events to add, update, or remove client-side signals.

Serializer behavior omits default-equivalent wire fields: data: onlyIfMissing ... is emitted only when #:only-if-missing? is #t, and retry: ... is emitted only when #:retry-duration is non-default.

Dot notation paths are expanded to nested objects, so "user.name" becomes {"user":{"name":null}}.

1.2.5 Elements🔗ℹ

Send element patch events to morph, insert, replace, or remove DOM content.

The #:mode parameter controls how elements are patched. Use symbol values; see element-patch-mode/c for allowed values.

Serializer behavior omits default-equivalent wire fields: data: mode ... is omitted for 'outer, data: namespace ... is omitted for 'html, data: useViewTransition ... is omitted for #f, and retry: ... is omitted for the default retry duration.

(patch-elements sse "<div id=\"out\">hello</div>")

(patch-elements sse "<svg>...</svg>" #:namespace 'svg)

(patch-elements sse "<li>item</li>" #:selector "#list" #:mode 'append)

(patch-elements/xexprs sse '(div ((id "out")) "hello"))

(patch-elements/xexprs sse '(svg "...") #:namespace 'svg)

(patch-elements/xexprs sse

'((li "one")

(li "two"))

#:selector "#list"

#:mode 'append)

Contracts used by patch-elements and patch-elements/xexprs option arguments:

1.2.6 Scripts🔗ℹ

Run browser-side scripts from SSE responses. See Datastar script execution guidance for expression semantics.

1.2.7 Compression🔗ℹ

Compress SSE responses by wrapping your app handler with wrap-compress from web-server-compress:

(require datastar

web-server-compress

web-server/dispatch

web-server/servlet-dispatch

web-server/web-server)

(define (events-handler req)

(datastar-sse (lambda (sse) ...)))

(define-values (app _uri) (dispatch-rules ...))

(serve #:dispatch (dispatch/servlet (wrap-compress app)) ...)

By default, wrap-compress negotiates with the client’s Accept-Encoding header using server-priority order: zstd first, then Brotli. If the client doesn’t support either, responses pass through uncompressed. Each SSE event is flushed to the client immediately.

To customize the encoding priority or tune per-encoding parameters:

(wrap-compress app

#:encodings '(br zstd)

#:brotli-quality 9

#:zstd-level 6)

For single-encoding use, wrap-brotli-compress and wrap-zstd-compress are also available. See the web-server-compress docs for the full API.