Liking cljdoc? Tell your friends :D
Mostly clj/s.
Exceptions indicated.

taoensso.sente

Channel sockets for Clojure/Script.

    Protocol  | client>server | client>server ?+ ack/reply | server>user push
  * WebSockets:       ✓              [1]                           ✓
  * Ajax:            [2]              ✓                           [3]

  [1] Emulate with cb-uuid wrapping
  [2] Emulate with dummy-cb wrapping
  [3] Emulate with long-polling

Terminology:
  * chsk      - Channel socket (Sente's own pseudo "socket")
  * server-ch - Underlying web server's async channel that implement
                Sente's server channel interface
  * sch       - server-ch alias
  * uid       - User-id. An application-level user identifier used for async
                push. May have semantic meaning (e.g. username, email address),
                may not (e.g. client/random id) - app's discretion.
  * cb        - Callback
  * tout      - Timeout
  * ws        - WebSocket/s
  * packed    - Arbitrary Clojure value serialized for client<->server comms
  * udt       - Unix timestamp (datetime long)

Special messages:
  * Callback wrapping: [<clj> <?cb-uuid>] for [1], [2]
  * Callback replies: :chsk/closed, :chsk/timeout, :chsk/error

  * Client-side events:
      [:chsk/ws-ping] ; ws-ping from server
      [:chsk/handshake [<?uid> nil <?handshake-data> <first-handshake?>]]
      [:chsk/state     [<old-state-map> <new-state-map> <open-change?>]]
      [:chsk/recv      <ev-as-pushed-from-server>] ; Server>user push

  * Server-side events:
      [:chsk/ws-ping] ; ws-ping from client
      [:chsk/ws-pong] ; ws-pong from client
      [:chsk/uidport-open  <uid>]
      [:chsk/uidport-close <uid>]
      [:chsk/bad-event     <event>]

Channel socket state map:
  :type               - e/o #{:auto :ws :ajax}
  :open?              - Truthy iff chsk appears to be open (connected) now
  :ever-opened?       - Truthy iff chsk handshake has ever completed successfully
  :first-open?        - Truthy iff chsk just completed first successful handshake
  :uid                - User id provided by server on handshake,    or nil
  :handshake-data     - Arb user data provided by server on handshake
  :last-ws-error      - ?{:udt _ :ev <WebSocket-on-error-event>}
  :last-ws-close      - ?{:udt _ :ev <WebSocket-on-close-event>
                          :clean? _ :code _ :reason _}
  :last-close         - ?{:udt _ :reason _}, with reason e/o
                          #{nil :clean :unexpected :requested-disconnect
                            :requested-reconnect :downgrading-ws-to-ajax
                            :ws-ping-timeout :ws-error}
  :udt-next-reconnect - Approximate udt of next scheduled auto-reconnect attempt

Notable implementation details:
  * core.async is used liberally where brute-force core.async allows for
    significant implementation simplifications. We lean on core.async's
    efficiency here.
  * For WebSocket fallback we use long-polling rather than HTTP 1.1 streaming
    (chunked transfer encoding). Http-kit _does_ support chunked transfer
    encoding but a small minority of browsers &/or proxies do not. Instead of
    implementing all 3 modes (WebSockets, streaming, long-polling) - it seemed
    reasonable to focus on the two extremes (performance + compatibility).
    In any case client support for WebSockets is growing rapidly so fallback
    modes will become increasingly irrelevant while the extra simplicity will
    continue to pay dividends.

General-use notes:
  * Single HTTP req+session persists over entire chsk session but cannot
    modify sessions! Use standard a/sync HTTP Ring req/resp for logins, etc.
  * Easy to wrap standard HTTP Ring resps for transport over chsks. Prefer
    this approach to modifying handlers (better portability).

*simulated-bad-conn-rate*clj/s

Debugging tool. Proportion ∈ℝ[0,1] of connection activities to sabotage.
source

ajax-callcljs

Alias of `taoensso.encore/ajax-call`
source

allow-origin?clj/s

(allow-origin? allowed-origins ring-req)
Alpha, subject to change.
Returns true iff given Ring request is allowed by `allowed-origins`.
`allowed-origins` may be `:all` or #{<origin> ...}.
source

as-eventclj/s

(as-event x)
source

assert-eventclj/s

(assert-event x)
Returns given argument if it is a valid [ev-id ?ev-data] form. Otherwise
throws a validation exception.
source

cb-error?clj/s

(cb-error? arb-reply-clj)
source

cb-success?clj/s

(cb-success? arb-reply-clj)
source

chsk-break-connection!clj/s

(chsk-break-connection! chsk)
(chsk-break-connection! chsk {:keys [close-ws?] :as opts :or {close-ws? true}})
Breaks channel socket's underlying connection without doing a clean
disconnect as in `chsk-disconnect!`. Useful for simulating broken
connections in testing, etc.

Options:

  `:close-ws?` - (Default: true)
    Allow WebSocket's `on-close` event to fire?
    Set to falsey to ~simulate a broken socket that doesn't realise
    it's broken.
source

chsk-connect!clj/s

(chsk-connect! chsk)
source

chsk-disconnect!clj/s

(chsk-disconnect! chsk)
source

chsk-reconnect!clj/s

(chsk-reconnect! chsk)
Cycles connection, useful for reauthenticating after login/logout, etc.
source

chsk-send!clj/s

(chsk-send! chsk ev)
(chsk-send! chsk ev opts)
(chsk-send! chsk ev ?timeout-ms ?cb)
Sends `[ev-id ev-?data :as event]`, returns true on apparent success.
source

client-event-msg?clj/s

(client-event-msg? x)
source

client-unloading?_clj/s

source

event-msg?clj/s

Alias for:
Cljs: `client-event-msg?`.
Clj:  `server-event-msg?`.

If you're using a Clj client or Cljs server, use the above utils
directly instead.
source

event?clj/s

(event? x)
Valid [ev-id ?ev-data] form?
source

IChSocketclj/sprotocol

-chsk-break-connection!clj/s

(-chsk-break-connection! chsk opts)

-chsk-connect!clj/s

(-chsk-connect! chsk)

-chsk-disconnect!clj/s

(-chsk-disconnect! chsk reason)

-chsk-reconnect!clj/s

(-chsk-reconnect! chsk reason)

-chsk-send!clj/s

(-chsk-send! chsk ev opts)
source

make-channel-socket!clj/s

Alias for:
Cljs: `make-channel-socket-client!`.
Clj:  `make-channel-socket-server!`.

If you're using a Clj client or Cljs server, use the above utils
directly instead. See above docstrings for details.
source

make-channel-socket-client!clj/s≠

clj
(make-channel-socket-client!
  path
  ?csrf-token-or-fn
  &
  [{:as opts
    :keys [type protocol host port params headers recv-buf-or-n packer
           ws-constructor ws-kalive-ms ws-ping-timeout-ms ws-opts client-id
           ajax-opts wrap-recv-evs? backoff-ms-fn]
    :or {ws-ping-timeout-ms 5000
         ws-kalive-ms 20000
         ws-constructor nil
         client-id (or (:client-uuid opts) (enc/uuid-str))
         packer :edn
         type :auto
         recv-buf-or-n (async/sliding-buffer 2048)
         backoff-ms-fn enc/exp-backoff
         wrap-recv-evs? false}}])
cljs
(make-channel-socket-client!
  path
  ?csrf-token-or-fn
  &
  [{:as opts
    :keys [type protocol host port params headers recv-buf-or-n packer
           ws-constructor ws-kalive-ms ws-ping-timeout-ms ws-opts client-id
           ajax-opts wrap-recv-evs? backoff-ms-fn]
    :or {ws-ping-timeout-ms 5000
         ws-kalive-ms 20000
         ws-constructor make-client-ws
         client-id (or (:client-uuid opts) (enc/uuid-str))
         packer :edn
         type :auto
         recv-buf-or-n (async/sliding-buffer 2048)
         backoff-ms-fn enc/exp-backoff
         wrap-recv-evs? false}}])
Returns nil on failure, or a map with keys:
  :ch-recv ; core.async channel to receive `event-msg`s (internal or from
           ; clients). May `put!` (inject) arbitrary `event`s to this channel.
  :send-fn ; (fn [event & [?timeout-ms ?cb-fn]]) for client>server send.
  :state   ; Watchable, read-only (atom {:type _ :open? _ :uid _ :csrf-token _}).
  :chsk    ; IChSocket implementer. You can usu. ignore this.

Required arguments:
  path              ; Channel socket server route/path (typically `/chsk`)
  ?csrf-token-or-fn ; CSRF string or (fn [])->string to match token expected by server.
                    ; nil => server not expecting any CSRF token.

Common options:
  :type           ; e/o #{:auto :ws :ajax}. You'll usually want the default (:auto).
  :protocol       ; Server protocol, e/o #{:http :https}.
  :host           ; Server host (defaults to current page's host).
  :port           ; Server port (defaults to current page's port).
  :params         ; Map of any params to incl. in chsk Ring requests (handy
                  ; for application-level auth, etc.).
  :headers        ; Map of additional headers to include in the initiating request
                  ; (currently only for Java clients).
  :packer         ; :edn (default), or an IPacker implementation.
  :ajax-opts      ; Base opts map provided to `taoensso.encore/ajax-call`, see
                  ; relevant docstring for more info.
  :wrap-recv-evs? ; Should events from server be wrapped in [:chsk/recv _]?

  :ws-kalive-ms       ; Max msecs to allow WebSocket inactivity before client sends ping to server.
  :ws-ping-timeout-ms ; Max msecs to wait for ws-kalive ping response before concluding conn is broken.

  :ws-constructor ; Advanced, (fn [{:keys [uri-str headers on-message on-error on-close]}]
                  ; => nil or delay that can be dereffed to get a connected `ClientWebSocket`.
source

make-channel-socket-server!clj/s

(make-channel-socket-server!
  web-server-ch-adapter
  &
  [{:keys [recv-buf-or-n ws-kalive-ms lp-timeout-ms ws-ping-timeout-ms
           send-buf-ms-ajax send-buf-ms-ws user-id-fn bad-csrf-fn bad-origin-fn
           csrf-token-fn handshake-data-fn packer allowed-origins authorized?-fn
           unauthorized-fn ?unauthorized-fn ms-allow-reconnect-before-close-ws
           ms-allow-reconnect-before-close-ajax]
    :or {ws-ping-timeout-ms (enc/ms :secs 5)
         ws-kalive-ms (enc/ms :secs 25)
         send-buf-ms-ws 30
         allowed-origins :all
         lp-timeout-ms (enc/ms :secs 20)
         ms-allow-reconnect-before-close-ws 2500
         csrf-token-fn
           (fn [ring-req]
               (or (:anti-forgery-token ring-req)
                   (get-in ring-req [:session :csrf-token])
                   (get-in ring-req
                           [:session
                            :ring.middleware.anti-forgery/anti-forgery-token])
                   (get-in ring-req [:session "__anti-forgery-token"])))
         packer :edn
         ms-allow-reconnect-before-close-ajax 5000
         unauthorized-fn (fn [_ring-req]
                             {:status 401 :body "Unauthorized request"})
         send-buf-ms-ajax 100
         bad-origin-fn (fn [_ring-req]
                           {:status 403 :body "Unauthorized origin"})
         handshake-data-fn (fn [ring-req] nil)
         user-id-fn (fn [ring-req] (get-in ring-req [:session :uid]))
         recv-buf-or-n (async/sliding-buffer 1000)
         bad-csrf-fn (fn [_ring-req] {:status 403 :body "Bad CSRF token"})}}])
Takes a web server adapter[1] and returns a map with keys:

  :ch-recv ; core.async channel to receive `event-msg`s (internal or from clients).
  :send-fn                     ; (fn [user-id ev] for server>user push.
  :ajax-post-fn                ; Ring handler for CSRF-POST + chsk URL.
  :ajax-get-or-ws-handshake-fn ; Ring handler for Ring GET  + chsk URL.
  :connected-uids ; Watchable, read-only (atom {:ws #{_} :ajax #{_} :any #{_}}).

Security options:

  :allowed-origins   ; e.g. #{"http://site.com" ...}, defaults to :all. ; Alpha

  :csrf-token-fn     ; ?(fn [ring-req]) -> CSRF-token for Ajax POSTs and WS handshake.
                     ; nil fn or `:sente/skip-CSRF-check` return val => CSRF check will be
                     ; SKIPPED (can pose a *CSRF SECURITY RISK* for website use cases, so
                     ; please ONLY do this check if you're very sure you understand the
                     ; security implications!).

  :authorized?-fn    ; ?(fn [ring-req]) -> When non-nil, (authorized?-fn <ring-req>)
                     ; must return truthy, otherwise connection requests will be
                     ; rejected with (unauthorized-fn <ring-req>) response.
                     ;
                     ; May check Authroization HTTP header, etc.

  :?unauthorized-fn  ; An alternative API to `authorized?-fn`+`unauthorized-fn` pair.
                     ; ?(fn [ring-req)) -> <?rejection-resp>. I.e. when return value
                     ; is non-nil, connection requests will be rejected with that
                     ; non-nil value.

Other common options:

  :user-id-fn         ; (fn [ring-req]) -> unique user-id for server>user push.
  :handshake-data-fn  ; (fn [ring-req]) -> arb user data to append to handshake evs.
  :lp-timeout-ms      ; Timeout (repoll) long-polling Ajax conns after given msecs.
  :send-buf-ms-ajax   ; [2]
  :send-buf-ms-ws     ; [2]
  :packer             ; :edn (default), or an IPacker implementation.

  :ws-kalive-ms       ; Max msecs to allow WebSocket inactivity before server sends ping to client.
  :ws-ping-timeout-ms ; Max msecs to wait for ws-kalive ping response before concluding conn is broken.

  ;; When a connection is closed, Sente waits a little for possible reconnection before
  ;; actually marking the connection as closed. This facilitates Ajax long-polling,
  ;; server->client buffering, and helps to reduce event noise from spotty connections.
  :ms-allow-reconnect-before-close-ws   ; Msecs to wait for WebSocket conns (default: 2500)
  :ms-allow-reconnect-before-close-ajax ; Msecs to wait for Ajax      conns (default: 5000)

[1] e.g. `(taoensso.sente.server-adapters.http-kit/get-sch-adapter)` or
         `(taoensso.sente.server-adapters.immutant/get-sch-adapter)`.
    You must have the necessary web-server dependency in your project.clj and
    the necessary entry in your namespace's `ns` form.

[2] Optimization to allow transparent batching of rapidly-triggered
    server>user pushes. This is esp. important for Ajax clients which use a
    (slow) reconnecting poller. Actual event dispatch may occur <= given ms
    after send call (larger values => larger batch windows).
source

sente-versionclj/s

Useful for identifying client/server mismatch
source

server-event-msg?clj/s

(server-event-msg? x)
source

start-chsk-router!clj/s

Alias for:
Cljs: `start-client-chsk-router!`.
Clj:  `start-server-chsk-router!`.

If you're using a Clj client or Cljs server, use the above utils
directly instead. See above docstrings for details.
source

start-client-chsk-router!clj/s

(start-client-chsk-router! ch-recv
                           event-msg-handler
                           &
                           [{:as opts :keys [trace-evs? error-handler]}])
Creates a simple go-loop to call `(event-msg-handler <server-event-msg>)`
and log any errors. Returns a `(fn stop! [])`. Note that advanced users may
prefer to just write their own loop against `ch-recv`.

Nb performance note: since your `event-msg-handler` fn will be executed
within a simple go block, you'll want this fn to be ~non-blocking
(you'll especially want to avoid blocking IO) to avoid starving the
core.async thread pool under load. To avoid blocking, you can use futures,
agents, core.async, etc. as appropriate.
source

start-server-chsk-router!clj/s

(start-server-chsk-router!
  ch-recv
  event-msg-handler
  &
  [{:as opts :keys [trace-evs? error-handler simple-auto-threading?]}])
Creates a simple go-loop to call `(event-msg-handler <server-event-msg>)`
and log any errors. Returns a `(fn stop! [])`. Note that advanced users may
prefer to just write their own loop against `ch-recv`.

Nb performance note: since your `event-msg-handler` fn will be executed
within a simple go block, you'll want this fn to be ~non-blocking
(you'll especially want to avoid blocking IO) to avoid starving the
core.async thread pool under load. To avoid blocking, you can use futures,
agents, core.async, etc. as appropriate.

Or for simple automatic future-based threading of every request, enable
the `:simple-auto-threading?` opt (disabled by default).
source

validate-eventclj/s

(validate-event x)
Returns nil if given argument is a valid [ev-id ?ev-data] form. Otherwise
returns a map of validation errors like `{:wrong-type {:expected _ :actual _}}`.
source

cljdoc is a website building & hosting documentation for Clojure/Script libraries

Keyboard shortcutsReport a problemcljdoc on GitHub
× close