(index ("passphrase->key" 0) ("open-connection!" 273) ("connection?" 1746) ("connection-user" 1887) ("connection-addr" 2051) ("close-connection!" 2182) ("request!" 2282) ("remote-error?" 2972) ("remote-error-message" 3111) ("start-server" 3278) ("stop-server!" 4846) ("wait-until-server-stopped" 4943))
(def (sig (procedure "(passphrase->key passphrase-string)" (id passphrase->key))) (p "Converts an arbitrary passphrase string into a key object that can be used as an argument to " (tt "open-connection!") " or returned from a server's " (tt "username->key") " callback."))
(def (sig (procedure "(open-connection! address username key request-handler close-handler)" (id open-connection!))) (p "Opens a connection, returning a connection object.") (p (tt "address") " can be in any of the following forms:") (ul (li (tt "\"HOSTNAME:PORT\"") " or " (tt "(tcp HOSTNAME PORT)") " for a TCP connection") (li (tt "\"PATH/TO/SOCKET\"") " or " (tt "(unix \"PATH/TO/SOCKET\")") " for a UNIX domain connection")) (p (tt "username") " and " (tt "key") " will be used to authenticate and encrypt the connection; the server can't accept the connection unless the key matches what it expects for that username. So if you or the server have not got the right key, the connection will fail.") (p "For an unencrypted and unauthenticated insecure connection, set " (tt "username") " and " (tt "key") " to " (tt "#f") ".") (p (tt "request-handler") " is a callback that will be invoked (in a thread) for any requests that come from the server. It will be applied to two arguments: the connection object itself and the request received from the server. Its return value will be taken as the response to the request and sent back to the server. Any errors raised in the request-handler will be sent back to the server.") (p (tt "close-handler") " is a callback that will be invoked (in a thread) if the connection is closed by the server. It will be applied to a single argument, the connection object.") (p (tt "open-connection") " returns the connection object."))
(def (sig (procedure "(connection? con)" (id connection?))) (p "Returns " (tt "#t") " if and only if the argument is a connection object."))
(def (sig (procedure "(connection-user con)" (id connection-user))) (p "Returns the username of the connection, or " (tt "#f") " if it's an insecure connection."))
(def (sig (procedure "(connection-addr con)" (id connection-addr))) (p "Returns the address of the other end of the connection."))
(def (sig (procedure "(close-connection! con)" (id close-connection!))) (p "Closes a connection."))
(def (sig (procedure "(request! con message)" (id request!))) (p "Sends the " (tt "message") " (an arbitrary sexpr) as a request to the other end of the connection, and blocks waiting for a response. This is thread-safe - multiple threads may call " (tt "request!") " on the same connection in parallel, and although the connection is blocked while a request is being sent or a response received, it is not blocked while a request is being processed at the other end, and responses may come back in a different order to the requests sent.") (p "If the request fails for networky reasons, a suitable error is raised; if the request handler at the far end fails, a remote error is raised."))
(def (sig (procedure "(remote-error? error)" (id remote-error?))) (p "Returns " (tt "#t") " if and only if the error is a remote error."))
(def (sig (procedure "(remote-error-message error)" (id remote-error-message))) (p "Returns a string describing what went wrong at the other end of the connection."))
(def (sig (procedure "(start-server bind-addr backlog user->key open-handler request-handler close-handler)" (id start-server))) (p "Starts a bokbok server in a thread, and returns a server object.") (p (tt "bind-addr") " is the address to bind to, either " (tt "(unix PATH)") " for a Unix-domain socket or " (tt "(tcp ADDRESS PORT)") " for a TCP socket. An " (tt "ADDRESS") " of " (tt "#f") " causes it to bind on all available addresses.") (p (tt "backlog") " is the listen backlog. This is a slightly mysterious tuning parameter that can matter in highly-loaded systems. Try using " (tt "10") ".") (p (tt "user->key") ", if provided, is a callback closure invoked to authenticate and authorize encrypted connections. It is passed a username string, and must return a key object that matches the key object used by the client when opening the connection. Attach it to whatever passes for a database of users on the server. It should return " (tt "#f") " for an unrecognised or otherwise not allowed to connect username. If " (tt "#f") " is provided, then the server listens for insecure connections.") (p (tt "open-handler") " is a callback closure invoked whenever a new connection is made to the server. It is applied to the connection object.") (p (tt "request-handler") " is a callback closure invoked whenever the client sends a request to the server on any connection, as explained above under " (tt "open-connection") ".") (p (tt "close-handler") " is a callback closure invoked when the client closes a connection. It is applied to the connection object."))
(def (sig (procedure "(stop-server! server)" (id stop-server!))) (p "Asks the server to stop."))
(def (sig (procedure "(wait-until-server-stopped server)" (id wait-until-server-stopped))) (p "Blocks until the server has stopped."))
