https://github.com/jarohen/chord
A library designed to bridge the gap between the triad of CLJ/CLJS, web-sockets and core.async.
https://github.com/jarohen/chord
Last synced: 30 days ago
JSON representation
A library designed to bridge the gap between the triad of CLJ/CLJS, web-sockets and core.async.
- Host: GitHub
- URL: https://github.com/jarohen/chord
- Owner: jarohen
- Created: 2013-08-03T14:04:48.000Z (almost 12 years ago)
- Default Branch: master
- Last Pushed: 2020-07-12T09:57:33.000Z (almost 5 years ago)
- Last Synced: 2024-10-30T01:59:52.108Z (6 months ago)
- Language: Clojure
- Homepage:
- Size: 147 KB
- Stars: 439
- Watchers: 11
- Forks: 40
- Open Issues: 7
-
Metadata Files:
- Readme: README.org
- Changelog: CHANGES.org
Awesome Lists containing this project
README
* Chord
A lightweight Clojure/ClojureScript library designed to bridge the gap
between the triad of CLJ/CLJS, web-sockets and core.async.
** Usage
Include the following in your =project.clj=:
#+BEGIN_SRC clojure
[jarohen/chord "0.8.1"]
#+END_SRC
Chord now supports EDN, JSON, Transit and Fressian out of the box -
please remove dependencies to 'chord-fressian' and 'chord-transit' if
you have them. Thanks to [[https://github.com/lsnape][Luke Snape]], [[https://github.com/rosejn][Jeff Rose]] and [[https://github.com/tgetgood][Thomas Getgood]] for
their help supporting these formats!
*** Example project
There is a simple example server/client project under the
=example-project= directory. The client sends websocket messages to
the server, that get echoed back to the client and written on the
page.
You can run it with =lein dev= - an alias that starts up an http-kit
server using [[https://github.com/james-henderson/lein-frodo][Frodo]] and automatically re-compiles the CLJS.
Once it is running - navigate to [[http://localhost:3000/]] and you should see =Send a message to the server:=
*** ClojureScript
*Chord* only has one function, =chord.client/ws-ch=, which takes a
web-socket URL and returns a map, containing either =:ws-channel= or
=:error=. When the connection opens successfully, this channel then
returns a two-way channel that you can use to communicate with the
web-socket server:
#+BEGIN_SRC clojure
(:require [chord.client :refer [ws-ch]]
[cljs.core.async :refer [! put! close!]])
(:require-macros [cljs.core.async.macros :refer [go]])
(go
(let [{:keys [ws-channel error]} (! ws-channel "Hello server from client!")
(js/console.log "Error:" (pr-str error)))))
#+END_SRC
Messages that come from the server are received as a map with a
=:message= key:
#+BEGIN_SRC clojure
(go
(let [{:keys [ws-channel]} (! put! close! go]])
(defn your-handler [req]
(with-channel req ws-ch
(go
(let [{:keys [message]} (! ws-ch "Hello client from server!")
(close! ws-ch)))))
#+END_SRC
This can take a =:format= option, and custom buffered read/write
channels as well:
#+BEGIN_SRC clojure
(require '[clojure.core.async :as a])
(defn your-handler [req]
(with-channel req ws-ch
{:read-ch (a/chan (a/dropping-buffer 10))
:format :str} ; again, :edn is default
(go
(let [{:keys [message]} (! ws-ch "Hello client from server!")
(close! ws-ch)))))
#+END_SRC
You can also use the =wrap-websocket-handler= middleware, which will
put a =:ws-channel= key in the request map:
#+BEGIN_SRC clojure
(require '[chord.http-kit :refer [wrap-websocket-handler]]
'[org.httpkit.server :refer [run-server]]
'[clojure.core.async :as a])
(defn your-handler [{:keys [ws-channel] :as req}]
(go
(let [{:keys [message]} (! ws-channel "Hello client from server!")
(close! ws-channel))))
(run-server (-> #'your-handler wrap-websocket-handler) {:port 3000})
#+END_SRC
You can pass custom channels to =wrap-websocket-handler= as a second
(optional) parameter:
#+BEGIN_SRC clojure
(run-server (-> #'your-handler
(wrap-websocket-handler {:read-ch ...}))
{:port 3000})
#+END_SRC
** Bug reports/pull requests/comments/suggestions etc?
Yes please! Please submit these in the traditional GitHub manner.
** Contributors
Chord's contributors are listed in the ChangeLog - thank you all for
your help!
** License
Copyright © 2013-2015 James Henderson
Distributed under the Eclipse Public License, the same as Clojure.