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

Advanced option, most users can ignore this var. Only necessary
for those that want to use Sente < v1.18 with a non-standard
IPacker that deals with non-string payloads.

Details:
  Sente uses a private message format as an implementation detail
  for client<->server comms.

  As part of [#398], this format is being updated to support
  non-string (e.g. binary) payloads.

  Unfortunately updating the format is non-trivial because:
    1. Both the client & server need to support the same format.
    2. Clients are often served as cached cl/js.

  To help ease migration, the new pack format is being rolled out
  in stages:

    Sente <= v1.16: reads  v1 format only
                    writes v1 format only

    Sente    v1.17: reads  v1 and v2 formats
                    writes v1 and v2 formats (v1 default)

    Sente    v1.18: reads  v1 and v2 formats
                    writes v1 and v2 formats (v2 default)  <- Currently here

    Sente >= v1.19: reads  v2 format only
                    writes v2 format only

  This var controls which format to use for writing.
  Override default with `alter-var-root` or `binding`.

Alias of `taoensso.encore/ajax-call`

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

Returns given argument if it is a valid [ev-id ?ev-data] form. Otherwise
throws a validation exception.

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.

Cycles connection, useful for reauthenticating after login/logout, etc.

Sends `[ev-id ev-?data :as event]`, returns true on apparent success.

Valid [ev-id ?ev-data] form?

Platform-specific alias for `make-channel-socket-server!` or
`make-channel-socket-client!`. Please see the appropriate aliased fn
 docstring for details.

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 _]?
                  ; Default false for Sente >= v1.18, true otherwise.

  :ws-kalive-ms       ; Ping to keep a WebSocket conn alive if no activity
                      ; w/in given msecs. Should be different to server's :ws-kalive-ms.
  :ws-ping-timeout-ms ; When pinging to test WebSocket connections, msecs to
                      ; await reply before regarding the connection as 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 WebSocket.
                  ; See `default-client-ws-constructor` code for details.

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 => CSRF check will be DISABLED (can pose a *CSRF SECURITY RISK*
                     ; for website use cases, so please ONLY disable this check if you're
                     ; very sure you understand the 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.
  :ws-kalive-ms       ; Ping to keep a WebSocket conn alive if no activity
                      ; w/in given msecs. Should be different to client's :ws-kalive-ms.
  :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-ping-timeout-ms ; When pinging to test WebSocket connections, msecs to
                      ; await reply before regarding the connection as 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).

Useful for identifying client/server mismatch

Sets Timbre's minimum log level for internal Sente namespaces.
Possible levels: #{:trace :debug :info :warn :error :fatal :report}.
Default level: `:warn`.

Platform-specific alias for `start-server-chsk-router!` or
`start-client-chsk-router!`. Please see the appropriate aliased fn
docstring for details.

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.

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).

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 _}}`.