hyperfiddle.electric-ring-adapter3 — com.hyperfiddle/electric v3-alpha-7-gf499d2d1

Provide a wrap-electric-websocket Ring middleware, starting and managing an Electric Server. This is a Ring 1.11+ compliant, generic implementation. It is compatible with ring-jetty out of the box, and can be extended to other servers. See hyperfiddle.electric-httpkit-adapter for an example of an extension.

ELECTRIC-CONNECTION-TIMEOUT clj

Time after which the server will close the socket if it hasn't seen any websocket activity from the client.

ELECTRIC-HEARTBEAT-INTERVAL clj

Delay between two server-send ping-emulating messages. Used to keep the connection up.

electric-ws-handler clj

(electric-ws-handler ring-req boot-fn)

Return a map of generic ring-compliant handlers, describing how to start and manage an Electric server process hooked onto a websocket. Extensions (e.g. hyperfiddle.electric-httpkit-adapter) can extend the handler map as needed.

failure clj

(failure socket e)

Called on reactor termination, connection timeout, or reactor crash. A connection timeout or reactor crash will close the socket.

GENERIC-WS-CLOSE-MESSAGES clj

https://www.rfc-editor.org/rfc/rfc6455.html#section-7.4.1

handle-close-status-code clj multimethod

Perform an action on socket close, dispatching on status code. List of status code and their meaning: https://www.rfc-editor.org/rfc/rfc6455.html#section-7.4.1

Pingable clj protocol

ping clj

(ping this)

(ping this value)

pong clj

(pong this)

(pong this value)

reject-websocket-handler clj

(reject-websocket-handler code reason)

Will accept socket connection upgrade and immediately close the socket on connection, with given code and reason. Use this to cleanly reject a websocket connection.

ring-ws-handler clj

(ring-ws-handler ring-req boot-fn)

Return a Ring 1.11+ websocket listener starting and managing an Electric Server process.

send-hf-heartbeat clj

(send-hf-heartbeat delay ping!)

Socket clj protocol

An abstraction over various Socket impl. E.g. Ring-websocket Socket or HTTPKit AsyncChannel

close clj

(close this code)

(close this code reason)

open? clj

(open? this)

send clj

(send this value)

(send this value success-cb failure-cb)

timeout clj

(timeout mailbox time)

Throw if mailbox haven't got any message after given time ms

wrap-electric-websocket clj

(wrap-electric-websocket next-handler entrypoint)

A ring middleware starting an Electric server program defined by electric-boot-fn on websocket connection. E.g.:

(-> ring-handler
    (wrap-electric-websocket (fn [ring-req] (e/boot-server {} my-ns/MyElectricDefn ring-req)))
    (wrap-cookies)
    (wrap-params)
    ...
  )

wrap-reject-stale-client clj

(wrap-reject-stale-client next-handler config)

(wrap-reject-stale-client next-handler
                          {:keys [:hyperfiddle.electric/user-version]}
                          on-missmatch)

A Ring 1.11+ compatible middleware intercepting websocket UPGRADE request and checking if Electric client and Electric server versions matches. An Electric client is allowed to connect if:

• its version matches the server's version,
• the server does not have a defined version (dev mode). Otherwise, the websocket connection is gracefully rejected and the client is instructed to reload the page so to get new javascript assets.

The rejection action can be redefined by providing an on-mismatch callback argument taking:

• ring upgrade request,
• client-version,
• server-version, and returning the ring handler to be applied.

e.g. With ring-jetty 1.11+

(wrap-reject-stale-client handler {:hyperfiddle.electric/user-version nil})     ; will accept any client
(wrap-reject-stale-client handler {:hyperfiddle.electric/user-version "12345"}) ; will only accept clients of version 12345

With http-kit, which is not fully ring 1.11+ compliant as of Jan 9 2024

(wrap-reject-stale-client handler {:hyperfiddle.electric/user-version "12345"}
  (fn on-mismatch [ring-request client-version server-version]
    (log/info 'wrap-reject-stale-client ": Electric client connection was rejected because client version doesn't match the server version. Client was instructed to perform a page reload so to get new javascript assets."
      {:client-version (pr-str client-version)
       :server-version (pr-str server-version)})
    (httpkit/as-channel ring-request ; this is HTTPkit specific
      (electric-httpkit/reject-websocket-handler 1008 "stale client") ; Websocket close code 1008 instructs the Electric client of the version mismatch
    )))

write-msg clj

(write-msg socket message)

Return a task, writing a message on a websocket when run.

write-msgs clj

(write-msgs socket msgs)

Returns a task writing all messages emitted by flow on websocket.