clj-wamp.server documentation

add-client

(add-client channel-or-fn)
Adds a websocket channel (or callback function) to a map of clients
and returns a unique session id.

add-topic-prefix

(add-topic-prefix sess-id prefix uri)
Adds a new CURI topic prefix for a websocket client.

auth-challenge

(auth-challenge sess-id auth-key auth-secret)
Generates a challenge hash used by the client to sign the secret.

authorized?

(authorized? sess-id type topic perm-cb)
Checks if the session is authorized for a message type and topic.

broadcast-event!

(broadcast-event! topic event excludes)
Sends an event message to all clients in a topic but those excluded.

client-auth-requested?

(client-auth-requested? sess-id)
Checks if the authreq call has already occurred.

client-authenticated?

(client-authenticated? sess-id)
Checks if authentication has occurred.

del-client

(del-client sess-id)
Removes a websocket session from the map of clients.

emit-event!

(emit-event! topic event includes)
Sends an event message to specific clients in a topic

get-client-channel

(get-client-channel sess-id)
Returns the channel (or callback function) for a websocket client's
session id.

get-topic

(get-topic sess-id curi)
Returns the full topic URI for a prefix. If prefix does not exist,
returns the CURI passed in.

hmac-sha-256

(hmac-sha-256 key data)
Generates a HMAC SHA256 hash.

http-kit-handler

(http-kit-handler channel callbacks-map)
Sets up the necessary http-kit websocket event handlers
for use with the WAMP sub-protocol. Returns a WAMP client session id.

Example usage:

  (http-kit/with-channel req channel
    (if-not (:websocket? req)
      (http-kit/close channel)
      (http-kit-handler channel
        {:on-open        on-open-fn
         :on-close       on-close-fn

         :on-auth        {:allow-anon?     false         ; allow anonymous authentication?
                          :timeout         20000         ; default is 20 secs
                          :secret          auth-secret-fn
                          :permissions     auth-permissions-fn}

         :on-call        {(rpc-url "add")      +         ; map topics to rpc functions
                          (rpc-url "echo")     identity
                          :on-before           on-before-call-fn
                          :on-after-error      on-after-call-error-fn
                          :on-after-success    on-after-call-success-fn}

         :on-subscribe   {(evt-url "chat")     on-subscribe-fn? ; allowed to subscribe?
                          (evt-url "prefix*")  true             ; match topics by prefix
                          (evt-url "sub-only") true             ; implicitly allowed
                          (evt-url "pub-only") false            ; subscription is denied
                          :on-after            on-after-subscribe-fn};

         :on-publish     {(evt-url "chat")     on-publish-fn   ; custom event broker
                          (evt-url "prefix*")  true            ; pass events through as-is
                          (evt-url "sub-only") false           ; publishing is denied
                          (evt-url "pub-only") true
                          :on-after            on-after-publish-fn}

         :on-unsubscribe on-unsubscribe-fn})))

Callback signatures:

  (on-open-fn sess-id)
  (on-close-fn sess-id status)

  (auth-secret-fn sess-id auth-key auth-extra)
    Provide the authentication secret for the key (ie. username) and
    (optionally) extra information from the client. Return nil if the key
    does not exist.

  (auth-permissions-fn sess-id auth-key)
    Returns a map of permissions the session is granted when the authentication
    succeeds for the given key.

    The permission map should be comprised of the topics that are allowed
    for each category:

      {:rpc       {"http://example/rpc#call"    true}
       :subscribe {"http://example/event#allow" true
                   "http://example/event#deny"  false}
       :publish   {"http://example/event#allow" true}}

  (rpc-call ...)
    Can have any signature. The parameters received from the client will be applied as-is.
    The client session is also available in the bound *call-sess-id* var.
    The function may return a value as is, or in a result map: {:result "my result"},
    or as an error map: {:error {:uri "http://example.com/error#give-error"
                                 :message "Test error"
                                 :description "Test error description"
                                 :kill false}} ; true will close the connection after send

  (on-before-call-fn sess-id topic call-id call-params)
    To allow call, return params as vector: [sess-id topic call-id call-params]
    To deny, return nil/false.

  (on-after-call-error-fn sess-id topic call-id error)
    Return params as vector: [sess-id topic call-id error]

  (on-after-call-success-fn sess-id topic call-id result)
    Return params as vector: [sess-id topic call-id result]

  (on-subscribe-fn? sess-id topic)
    Return true to allow client to subscribe, false to deny.

  (on-after-subscribe-fn sess-id topic)
    No return values required.

  (on-publish-fn sess-id topic event exclude eligible)
    To allow publish, return params as vector: [sess-id topic event exclude eligible]
    To deny, return nil/false.

  (on-after-publish-fn sess-id topic event exclude eligible)
    No return values required.

  (on-unsubscribe-fn sess-id topic)
    No return values required.

origin-match?

(origin-match? origin-re req)
Compares a regular expression against the Origin: header.
Used to help protect against CSRF, but do not depend on just
this check. Best to use a server-generated CSRF token for comparison.

send-call-error!

(send-call-error! sess-id call-id err-uri err-desc)(send-call-error! sess-id call-id err-uri err-desc err-details)
Sends a WAMP call error message to a websocket client.
[ TYPE_ID_CALLERROR , callID , errorURI , errorDesc [, errorDetails] ]

send-call-result!

(send-call-result! sess-id call-id result)
Sends a WAMP call result message to a websocket client.
[ TYPE_ID_CALLRESULT , callID , result ]

send-event!

(send-event! topic event)
Sends an event message to all clients in topic.
[ TYPE_ID_EVENT , topicURI , event ]

send-welcome!

(send-welcome! sess-id)(send-welcome! sess-id protocol-ver server-ident)
Sends a WAMP welcome message to a websocket client.
[ TYPE_ID_WELCOME , sessionId , protocolVersion, serverIdent ]

subprotocol?

(subprotocol? proto req)
Checks if a protocol string exists in the Sec-WebSocket-Protocol
list header.

topic-subscribe

(topic-subscribe topic sess-id)
Subscribes a websocket session to a topic.

topic-unsubscribe

(topic-unsubscribe topic sess-id)
Unsubscribes a websocket session from a topic.

with-channel-validation

macro

(with-channel-validation request ch-name origin-re & body)
Replaces HTTP Kit with-channel macro to do extra validation
for the wamp subprotocol and allowed origin URLs.

Example usage:

  (defn my-wamp-handler [request]
    (wamp/with-channel-validation request channel #"https?://myhost"
      (wamp/http-kit-handler channel { ... })))

See org.httpkit.server for more information.