<h1>Introduction</h1>

Bokbok is a toolkit for exposing and consuming APIs between processes.

It supports:

  *  TCP or UNIX-domain sockets
  *  Optional encryption and authentication
  *  Multithreading over a single connection: multiple threads may
     make requests via the same connection, and multiple request handlers can be
     running at once in their own threads.
  *  Connections are symmetrical once established: either side may
     invoke the other side's API at any time, "client" and "server"
     are just a matter of who sat passively waiting for a connection
     and who initiated it.

<h1>Usage</h1>

<pre>$ chicken-install bokbok</pre>

<h2>As a client</h2>

<pre>(use bokbok)

;; Called if server sends us a callback request
(define (request-handler con request)
  (match request
   (("callback" num)
     (printf "Callback received: ~s\n" num))
   (else (error "Unrecognised callback"))))

;; Called if server closes the connection
(define (close-handler con)
  (void))

(define con (open-connection '(tcp "myserver" 12345)
             "myuser" (passphrase->key "mypassphrase")
             request-handler close-handler))

(printf "Response is ~s\n" (request! con '("ping" "12345")))

(printf "Response is ~s\n" (request! con '("asynch")))

;; Wait for asynch responses to all arrive
(thread-sleep! 10)

(close-connection! con)</pre>

<h2>As a server</h2>

<pre>(use bokbok)
(use matchable)

(define *server* #f)

(define (user->key username)
  (match username
   ("myuser" (passphrase->key "mypassphrase"))
   (else #f)))

(define (open-handler con)
  (printf "CONNECTION from ~a@~s\n"
    (connection-user con)
    (connection-addr con))
  (void))

(define (request-handler con request)
  (match request
    (("ping" string)
     (list "pong" string))
    (("asynch")
     (thread-start!
       (make-thread
         (lambda ()
           (request! con '("callback" "1"))
           (thread-sleep! 1)
           (request! con '("callback" "2"))
           (thread-sleep! 1)
           (request! con '("callback" "3"))
           (thread-sleep! 1)
           (request! con '("callback" "4")))))
     ;; Return this while the callback thread runs in the background
     (list "ok"))
    (("shutdown-server!")
     (stop-server! *server*))
    (else (error "Unknown request" request))
  ))

(define (close-handler con)
  (printf "DISCONNECTION from ~a@~s\n"
    (connection-user con)
    (connection-addr con))
  (void))

(set! *server* (start-server '(tcp #f 12345) 10 user->key
   open-handler request-handler close-handler)

(wait-until-0server-stopped server)</pre>

  (match request
         (("error")
          (error "Error raised"))
         (("callback")
          (let ((response
                 (request! con '("called you back"))))
            (thread-start!
             (make-thread
              (lambda ()
                (request! con '("callback" "1"))
                (thread-sleep! 1)
                (request! con '("callback" "2"))
                (thread-sleep! 1)
                (request! con '("callback" "3")))))
            (list "did it" (sprintf "~s" response))))
         (("kill")
          (if *server*
              (begin
                (stop-server! *server*)
                (list "ok"))
              (error "I'm not a server")))

(define (run-client! con)
  (expect '(ok ("echo" "hello"))
          (request! con '("hello")))
  (expect '(error ("\"Error raised\" in (#f)"))
          (request! con '("error")))
  (expect '(ok ("did it"  "(ok (\"echo\" \"called you back\"))"))
          (request! con '("callback")))
  (thread-sleep! 10)
#;  (expect '(ok ("ok"))
          (request! con '("kill")))
  (close-connection! con))

(define (run-server! server)
  (set! *server* server)
  (printf "Running server...\n")

                            (parameterize
                             ((socket-send-buffer-size 4096)
                              (socket-send-size 16384))
                             (socket-i/o-ports cs))
                            (let* ((peer (socket-peer-name cs))
                                   (peer-addr (if tcp?
                                                  (list 'tcp (sockaddr-address peer) (sockaddr-port peer))
                                                  (list 'unix (sockaddr-path peer)))))
                              (debug "Handshake thread started for ~s" peer-addr)
                              (if user->key
                                  ;; Encrypted connection
                                  (let* ((user-name (read-packet! input))
                                         (encrypted-session-key (read-packet! input)))
                                    (if (and (not (eof-object? user-name))
                                             (not (eof-object? encrypted-session-key)))