The intercom Reference Manual

Table of Contents

The intercom Reference Manual

This is the intercom Reference Manual, version 0.0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Feb 19 20:47:12 2020 GMT+0.

1 Introduction

h1. Intercom

Intercom is an easy to use library for high-level, bi-direcational communication between javascript and a lisp image with hunchentoot. It tries to optimize the amount of requests to the server and keeps the interface clean.

Features:
* JSON communication channel
* automatically adapting polling speed
* clean js and lisp RPC interface
* multiple responses per request
* requests can be canceled
* bundled requests and responses

h2. Simple Example

As a simple example, we create a remote procedure call which sends you a string every interval seconds, count times.

h3. Lisp implementation

To define a remote procedure in the lisp backend, you use the macro define-remote-procedure.

The first argument is the name of the remote procedure, which can be either a string or a symbol (which will be downcased). The following is an arg list, similar to what you would expect in a function definition. These values will be filled in with jsown objects (this can be lisp numbers, lisp lists, lisp strings or jsown representations of a javascript object).

Inside the body of the RPC definition, you have access to the message function. This sends a response for _this_ RPC to the client. The first argument is a type of the response, the second argument is a jsown instance, which represents the body. Remember, many lisp primitives are jsown objects.


  (define-remote-procedure echo (string count interval)
    (loop repeat count
       do (sleep interval)
	 (message "value" string))
    (message "ready" :true))



h3. Javascript implementation

The javascript side uses a ks.Intercom object to interact with the server. The intercom object is initialized with the url of the server. Requests are made to the /talk interface of the server.

To call a remote procedure on the server, you use the call function of an intercom object. This call function expects an object with the following properties: 

* *name* the name of the remote procedure to call
* *args* the arguments to be passed to the remote procedure, as a list of JSON objects or javascript primitives.
* *keys* when a message with this type is received, we stop listening for further requests for this RPC and call the onFinish function.
* *onResponse* this function gets called when we receive a message from the server. The entire message object is passed in as an argument.
* *onFinish* this function gets called when a message is received with a type in the keys list. It behaves exactly as the onResponse function.


  var intercom=new ks.Intercom({url:"/talk"});
  intercom.call({name:"test",
		    args:[10,2,1],
		    keys:["ready"],
		    onResponse:function(response){
			console.log("intermediate response: " +JSON.stringify(response));
		    },
		    onFinish:function(response){
			console.log("final response: "+ JSON.stringify(response));
		    }
		   });



The response argument that is passed in to the onResponse and onFinish function is a javascript object with the following properties:

* *type* the type of response that was provided by the server. If this type is contained in the keys list of the call, the onFinish function is called instead of the onResponse function.
* *body* the body of the response the actual content that is returned by the server.

h3. What happens on the wire

# Slow speed polling
# intercom.call(...)
# immediately send request + start high speed polling
# responses arrive
# ... 
# final resonse arrives + start slow speed polling

Or in prosaic format:

When no requests are running on the server, we poll the server at a slow speed (configurable through the defaultPollSpeed property of the intercom object in ms). When a call is made, this speed can be increased. At every poll to the server, we requests all messages that the server wishes to send and send them to the javascript client. At the client side, these responses are then handled by the appropriate request. When no active requests remain, the polling speed is decreased again.

The fast pollspeed when there are open requests is obtained by taking the minimum of the following properties:
* the minimum of the minSpeed properties of the open requests (for requests that specify this property) in ms.
* the minimum of the result of the getSpeedAfterTime function of the open requests if such a function is specified. This function accepts a time in ms since the request was accepted and returns the pollspeed in ms.
* the defaultPollSpeed property of the intercom object in ms.

Please note that the polling mechanism is used as a heartbeat as well. As a result, we have had to limit the minimum pollSpeed to one poll per ten seconds. Values of more than 10000 will be interpreted as being equal to the maximum. Values smaller than zero will be assumed equal to zero (poll as soon as possible).

h2. Javascript Features

The API that is provided on the javascript side consists of the ks.Intercom class and its three public functions: call, cancel and complete.

The call function has been described in some detail above. However, it is worth noting that the call function actually returns an object that can be used to cancel a request, as in the following example:


var request=intercom.call(
       {name:"echo",
	args:[{string:"foobar",
	       count:3,
	       interval:1}],
	keys:["ready"],
	onResponse:function(response){
	    console.log("received single response with body: "+response.body);
	},
	onFinish:function(response){
	    console.log("received final response with body: "+response.body);
	}
       });

...
    
results.intercom.cancel(request);



The cancel function expects an object that was created by the call function. It sends a message to the server to inform it that no further messages are required for the given request and also calls the complete function on the intercom object.

The complete function also expects an object that was created by the call function. It simply tells the intercom object to stop listening for messages for the given request. It does not inform the server about this, as it is assumed the server already knows (this happens for instance when the server sends a message with a finalizing type). Users are not recommended to use the complete function, they should use the keys list of a request instead.

h2. Lisp Features

the implementation on te lisp side offers two 'special' features when defininig remote procedure calls.

h3. RPC name

The name of the RPC can either be a string or a symbol. When a string is used, this name can be used (case sensitive) for identifying the RPC in the javascript call. When a symbol is used, it is downcased and the downcased name is used for the javascript call.

Let's build two example functions and check when each one is called when.


(define-remote-procedure echo (string)
  (message "result" string))

(define-remote-procedure "eCHo" (string)
  (message "result" (format nil "HELLO! ~A" string)))



The following javascript calls call both remote procedures.


intercom.call(
     {name:"echo",
      args:["Hello John"],
      keys:["result"],
      onFinish:function(response){
          console.log("echo resulted in " + response.body);
      }});

intercom.call(
     {name:"eCHo",
      args:["Hello Jake"],
      keys:["result"],
      onFinish:function(response){
          console.log("eCHo resulted in " + response.body);
      }});



They result in these messages to be logged on the console:


echo resulted in Hello John
eCHo resulted in HELLO! Hello Jake



h3. Keyword Arguments

The &key argument in the parameter list in the definition of a remote procedure would traditionally be nonsensical when coming from a list of javascript objects. There's no way to generate keyword symbols from the javascript side. The use of the &key argument list destructures the javascript object and fetches the keys with that name from the javascript object. The name of the key to fetch is the lowercased name of the symbol. This allows for a slightly more javascript-style of passing complex arguments.

Let's build two examples to show how this can make code i bit more readable.


(define-remote-procedure hello (friend-p &key first-name last-name)
  (message "result"
           (if friend-p
               (format nil "Hello ~A ~A" first-name last-name)
               (format nil "Hi ~A" first-name))))

(define-remote-procedure format-buy-car (&key title first-name last-name &key make type engine)
  (message "result"
           (format nil "~A ~A ~A is buying a ~A ~A with a ~A in it."
                   title first-name last-name make type engine)))



These examples can be called with the following javascript snippets:


intercom.call(
     {name:"hello",
      args:[false, {"first-name":"James", "last-name":"Dean"],
      keys:["result"],
      onFinish:function(response){
          console.log(response.body);
      }});

intercom.call(
     {name:"format-buy-car",
      args:[{title:"Mr.", "first-name":"Bill", "last-name":"Gates"},
            {make:"Seat",type:"Marbella",engine:"843cc"}],
      keys:["result"],
      onFinish:function(response){
          console.log(response.body);
      }});



h2. Performance Considerations

For every RPC a new thread is built. If you have a lot active threads, this can hose your system.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 intercom

Maintainer

Aad Versteden <aad@knowified.com>

Author

Aad Versteden <aad@knowified.com>

License

MIT

Description

Intercom allows bidirectional message passing between javascript and lisp.

Version

0.0.1

Dependencies

• jsown
• hunchentoot
• bordeaux-threads
• split-sequence
• alexandria

Source

intercom.asd (file)

Components

• packages.lisp (file)
• intercom.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 intercom.asd

Location

intercom.asd

Systems

intercom (system)

3.1.2 intercom/packages.lisp

Parent

intercom (system)

Location

packages.lisp

Packages

intercom

3.1.3 intercom/intercom.lisp

Dependency

packages.lisp (file)

Parent

intercom (system)

Location

intercom.lisp

Exported Definitions

• *hydra-body-timeout* (special variable)
• *hydra-head-timeout* (special variable)
• *log-request-stream* (special variable)
• *remote-procedure-context* (special variable)
• activep (function)
• add-screen-gc-callback (function)
• add-session-gc-callback (function)
• auto-end-remote-procedure-p (function)
• (setf auto-end-remote-procedure-p) (function)
• define-remote-procedure (macro)
• handle-talk-request (function)
• message (function)
• remove-screen-gc-callback (function)
• remove-session-gc-callback (function)
• screen-var (function)
• (setf screen-var) (function)
• session-var (function)
• (setf session-var) (function)
• threadable-lambda (macro)
• translate-remote-procedure-name (function)
• with-error-as-fail (macro)
• with-screen-db-lock (macro)
• with-session-db-lock (macro)

Internal Definitions

• *auto-kill-rid* (special variable)
• *current-thread-start-internal-runtime* (special variable)
• *hydra-auth-lock* (special variable)
• *hydra-auth-store* (special variable)
• *hydra-body* (special variable)
• *hydra-head* (special variable)
• *hydra-head-id* (special variable)
• *log-stream-lock* (special variable)
• *remote-procedures* (special variable)
• *rid* (special variable)
• assert-eql-compatible (macro)
• assert-hydra-body (macro)
• assert-hydra-head (macro)
• assert-hydra-session-validation (macro)
• assert-nonempty-string (macro)
• assert-session (function)
• attach-head (function)
• build-active-authentication (function)
• build-active-hydra-body (function)
• call-remote-procedure (function)
• close-request-logging (function)
• copy-hydra-body (function)
• copy-hydra-head (function)
• copy-key-value-store (function)
• copy-session-validation (function)
• discover-hydra (function)
• discover-hydra-body (function)
• ensure-hhid (function)
• ensure-hydra (function)
• ensure-hydra-head (function)
• esc (macro)
• fetch-and-clear-messages (function)
• gc-hydra-bodies (function)
• gc-hydra-body (function)
• gc-hydra-head (function)
• gc-hydra-heads (function)
• generate-id (function)
• get-remote-procedure (function)
• hash-keys (function)
• hydra-body (structure)
• hydra-body-active-p (function)
• hydra-body-atime (function)
• (setf hydra-body-atime) (function)
• hydra-body-data (function)
• (setf hydra-body-data) (function)
• hydra-body-garbage-collected-body-p (function)
• (setf hydra-body-garbage-collected-body-p) (function)
• hydra-body-gc-callbacks (function)
• (setf hydra-body-gc-callbacks) (function)
• hydra-body-heads (function)
• (setf hydra-body-heads) (function)
• hydra-body-p (function)
• hydra-head (structure)
• hydra-head-active-p (function)
• hydra-head-atime (function)
• (setf hydra-head-atime) (function)
• hydra-head-data (function)
• (setf hydra-head-data) (function)
• hydra-head-garbage-collected-body-p (function)
• (setf hydra-head-garbage-collected-body-p) (function)
• hydra-head-gc-callbacks (function)
• (setf hydra-head-gc-callbacks) (function)
• hydra-head-id (function)
• (setf hydra-head-id) (function)
• hydra-head-p (function)
• in-active-remote-procedure-p (function)
• in-intercom-session (macro)
• key-value-store (structure)
• key-value-store-hash (function)
• (setf key-value-store-hash) (function)
• key-value-store-lock (function)
• (setf key-value-store-lock) (function)
• key-value-store-p (function)
• kv-store-read (function)
• (setf kv-store-read) (function)
• make-hydra-body (function)
• make-hydra-head (function)
• make-key-value-store (function)
• make-log-message-string (function)
• make-remote-procedure-lambda-function (function)
• make-session-validation (function)
• maybe-log-request (macro)
• mk-session-validation (function)
• perform-close-request (function)
• perform-intercom-request (function)
• ping-logging (function)
• register-remote-procedure (function)
• remove-hydra-validation (function)
• remove-rid (function)
• request-logging (function)
• response-logging (function)
• retrieve-hydra-validations (function)
• rid-active-p (function)
• s+ (function)
• send-current-hhid (function)
• session-validation (structure)
• session-validation-host (function)
• (setf session-validation-host) (function)
• session-validation-hydra-body (function)
• (setf session-validation-hydra-body) (function)
• session-validation-hydra-id (function)
• (setf session-validation-hydra-id) (function)
• session-validation-p (function)
• session-validation-user-agent (function)
• (setf session-validation-user-agent) (function)
• start-rid (function)
• store-hydra-validation (function)
• talk (function)
• thread-initial-bindings (function)
• touch (generic function)
• touch (method)
• touch (method)
• valid-session-p (function)
• with-doublequotes (macro)
• with-hydra-auth-store-lock (macro)
• with-key-value-store-lock (macro)
• with-local-screen-lock (macro)

4 Packages

Packages are listed by definition order.

4.1 intercom

Source

packages.lisp (file)

Use List

• alexandria.1.0.0
• jsown
• common-lisp

Exported Definitions

• *hydra-body-timeout* (special variable)
• *hydra-head-timeout* (special variable)
• *log-request-stream* (special variable)
• *remote-procedure-context* (special variable)
• activep (function)
• add-screen-gc-callback (function)
• add-session-gc-callback (function)
• auto-end-remote-procedure-p (function)
• (setf auto-end-remote-procedure-p) (function)
• define-remote-procedure (macro)
• handle-talk-request (function)
• message (function)
• remove-screen-gc-callback (function)
• remove-session-gc-callback (function)
• screen-var (function)
• (setf screen-var) (function)
• session-var (function)
• (setf session-var) (function)
• threadable-lambda (macro)
• translate-remote-procedure-name (function)
• with-error-as-fail (macro)
• with-screen-db-lock (macro)
• with-session-db-lock (macro)

Internal Definitions

• *auto-kill-rid* (special variable)
• *current-thread-start-internal-runtime* (special variable)
• *hydra-auth-lock* (special variable)
• *hydra-auth-store* (special variable)
• *hydra-body* (special variable)
• *hydra-head* (special variable)
• *hydra-head-id* (special variable)
• *log-stream-lock* (special variable)
• *remote-procedures* (special variable)
• *rid* (special variable)
• assert-eql-compatible (macro)
• assert-hydra-body (macro)
• assert-hydra-head (macro)
• assert-hydra-session-validation (macro)
• assert-nonempty-string (macro)
• assert-session (function)
• attach-head (function)
• build-active-authentication (function)
• build-active-hydra-body (function)
• call-remote-procedure (function)
• close-request-logging (function)
• copy-hydra-body (function)
• copy-hydra-head (function)
• copy-key-value-store (function)
• copy-session-validation (function)
• discover-hydra (function)
• discover-hydra-body (function)
• ensure-hhid (function)
• ensure-hydra (function)
• ensure-hydra-head (function)
• esc (macro)
• fetch-and-clear-messages (function)
• gc-hydra-bodies (function)
• gc-hydra-body (function)
• gc-hydra-head (function)
• gc-hydra-heads (function)
• generate-id (function)
• get-remote-procedure (function)
• hash-keys (function)
• hydra-body (structure)
• hydra-body-active-p (function)
• hydra-body-atime (function)
• (setf hydra-body-atime) (function)
• hydra-body-data (function)
• (setf hydra-body-data) (function)
• hydra-body-garbage-collected-body-p (function)
• (setf hydra-body-garbage-collected-body-p) (function)
• hydra-body-gc-callbacks (function)
• (setf hydra-body-gc-callbacks) (function)
• hydra-body-heads (function)
• (setf hydra-body-heads) (function)
• hydra-body-p (function)
• hydra-head (structure)
• hydra-head-active-p (function)
• hydra-head-atime (function)
• (setf hydra-head-atime) (function)
• hydra-head-data (function)
• (setf hydra-head-data) (function)
• hydra-head-garbage-collected-body-p (function)
• (setf hydra-head-garbage-collected-body-p) (function)
• hydra-head-gc-callbacks (function)
• (setf hydra-head-gc-callbacks) (function)
• hydra-head-id (function)
• (setf hydra-head-id) (function)
• hydra-head-p (function)
• in-active-remote-procedure-p (function)
• in-intercom-session (macro)
• key-value-store (structure)
• key-value-store-hash (function)
• (setf key-value-store-hash) (function)
• key-value-store-lock (function)
• (setf key-value-store-lock) (function)
• key-value-store-p (function)
• kv-store-read (function)
• (setf kv-store-read) (function)
• make-hydra-body (function)
• make-hydra-head (function)
• make-key-value-store (function)
• make-log-message-string (function)
• make-remote-procedure-lambda-function (function)
• make-session-validation (function)
• maybe-log-request (macro)
• mk-session-validation (function)
• perform-close-request (function)
• perform-intercom-request (function)
• ping-logging (function)
• register-remote-procedure (function)
• remove-hydra-validation (function)
• remove-rid (function)
• request-logging (function)
• response-logging (function)
• retrieve-hydra-validations (function)
• rid-active-p (function)
• s+ (function)
• send-current-hhid (function)
• session-validation (structure)
• session-validation-host (function)
• (setf session-validation-host) (function)
• session-validation-hydra-body (function)
• (setf session-validation-hydra-body) (function)
• session-validation-hydra-id (function)
• (setf session-validation-hydra-id) (function)
• session-validation-p (function)
• session-validation-user-agent (function)
• (setf session-validation-user-agent) (function)
• start-rid (function)
• store-hydra-validation (function)
• talk (function)
• thread-initial-bindings (function)
• touch (generic function)
• touch (method)
• touch (method)
• valid-session-p (function)
• with-doublequotes (macro)
• with-hydra-auth-store-lock (macro)
• with-key-value-store-lock (macro)
• with-local-screen-lock (macro)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *hydra-body-timeout*

the time we have before we assume the session has ended.

Package

intercom

Source

intercom.lisp (file)

Special Variable: *hydra-head-timeout*

the time we have before we assume the head is detached.

Package

intercom

Source

intercom.lisp (file)

Special Variable: *log-request-stream*

when non-nil, this should be a character stream. an s-expression based log is written to the stream containing the ping-times, the requests and the responses for each user. the format is as follows:
- ping :: (ping utime hydra-body-id hydra-head-id ip-address)
- request :: (req utime hydra-body-id hydra-head-id request-id request-name arg1..argn)
- responses :: (res utime hydra-body-id hydra-head-id request-id time message-type message-value) - closes :: (close utime hydra-body-id hydra-head-id request-id)

Package

intercom

Source

intercom.lisp (file)

Special Variable: *remote-procedure-context*

should contain an alist in which the keywords are special variables and the values are evaluated (in the creating thread) each time a remote procedure is built. this allows you to pass special variables.

Package

intercom

Source

intercom.lisp (file)

5.1.2 Macros

Macro: define-remote-procedure NAME (&rest ARGUMENTS) &body BODY

defines a remote procedure with <name> as the name to be called and <arguments> as the assumed arguments. if <name> is a symbol with only non- lower-case-p characters, then it is converted to lowercase.

Package

intercom

Source

intercom.lisp (file)

Macro: threadable-lambda (&rest ARGLIST) &body BODY

creates a lambda which can be threaded. it locally binds the variables which are needed by intercom.

Package

intercom

Source

intercom.lisp (file)

Macro: with-error-as-fail &body BODY

executes <body> in an environment in which all errors are catched and sent as a message with type "fail" to the user.

Package

intercom

Source

intercom.lisp (file)

Macro: with-screen-db-lock (&optional SESSION) &body BODY

executes <body> with a lock on the datastore of hydra-head.
this should be used when the new value is based on previous values in the session.

Package

intercom

Source

intercom.lisp (file)

Macro: with-session-db-lock (&optional SESSION) &body BODY

executes <body> with a lock on the datastore of hydra-body.
this should be used when the new value is based on previous values in the session.

Package

intercom

Source

intercom.lisp (file)

5.1.3 Functions

Function: activep ()

returns non-nil if we are currently in an active remote procedure. alias for in-active-remote-procedure-p.

Package

intercom

Source

intercom.lisp (file)

Function: add-screen-gc-callback FUNCTION &optional SCREEN

adds <function> to the list of functions to call on garbage collection of <screen>.

Package

intercom

Source

intercom.lisp (file)

Function: add-session-gc-callback FUNCTION &optional SESSION

adds <function> to the list of functions to call on garbage collection of <session>.

Package

intercom

Source

intercom.lisp (file)

Function: auto-end-remote-procedure-p ()

returns non-nil iff the end of the current remote-procedure indicates that the rid should be killed. setfable place defaults to t.

Package

intercom

Source

intercom.lisp (file)

Writer

(setf auto-end-remote-procedure-p) (function)

Function: (setf auto-end-remote-procedure-p) VALUE

sets the killing of the remote-procedure to <value>. non-nil indicates that the remote-procedure should be killed (the default), nil indicates the inverse.

Package

intercom

Source

intercom.lisp (file)

Reader

auto-end-remote-procedure-p (function)

Function: handle-talk-request ()

handle-talk-request handles a talk request.
splitting this off allows us to handle talking when easy-handlers aren’t in use.

Package

intercom

Source

intercom.lisp (file)

Function: message TYPE BODY

sends a message to the client

Package

intercom

Source

intercom.lisp (file)

Function: remove-screen-gc-callback FUNCTION &optional SCREEN

removes <function> from the list of functions to call on the garbage collection of <screen>.

Package

intercom

Source

intercom.lisp (file)

Function: remove-session-gc-callback FUNCTION &optional SESSION

removes <function> from the list of functions to call on the garbage collection of <session>.

Package

intercom

Source

intercom.lisp (file)

Function: screen-var KEY &optional SCREEN

returns the value of <key> which belongs to <screen>, or nil if it didn’t exist. the second value is non-nil iff <key> was found in <screen>.

Package

intercom

Source

intercom.lisp (file)

Writer

(setf screen-var) (function)

Function: (setf screen-var) VALUE KEY &optional SCREEN

sets the value of ,key> which belongs to <screen> to <value>.

Package

intercom

Source

intercom.lisp (file)

Reader

screen-var (function)

Function: session-var KEY &optional SESSION

returns the value of <key> which belongs to <session>, or nil if it didn’t exist. the second value is non-nil iff <key> was found in <session>.

Package

intercom

Source

intercom.lisp (file)

Writer

(setf session-var) (function)

Function: (setf session-var) VALUE KEY &optional SESSION

sets the value of ,key> which belongs to <session> to <value>.

Package

intercom

Source

intercom.lisp (file)

Reader

session-var (function)

Function: translate-remote-procedure-name NAME

translates the remote procedure name <name> to the remote procedure name as can be called from the javascript world.

Package

intercom

Source

intercom.lisp (file)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *auto-kill-rid*

when this is set to non-nil in a given thread (which is the default for call-remote-procedure, then the ending of the call to call-remote-procedure signals the end of the rid. you can turn it on with #’auto-end-remote-procedure and turn it off with #’dont-auto-end-remote-procedure.

Package

intercom

Source

intercom.lisp (file)

Special Variable: *current-thread-start-internal-runtime*

contains the internal runtime when this RPC call was started.

Package

intercom

Source

intercom.lisp (file)

Special Variable: *hydra-auth-lock*

this lock is used when accessing the hydra-auth-store

Package

intercom

Source

intercom.lisp (file)

Special Variable: *hydra-auth-store*

a hash-table linking each "hydra" cookie value to the authentication which belongs to it.

Package

intercom

Source

intercom.lisp (file)

Special Variable: *hydra-body*

contains the hydra-body once we have a hydra-body in the current request

Package

intercom

Source

intercom.lisp (file)

Special Variable: *hydra-head*

contains the hydra-head once we have one in the current request

Package

intercom

Source

intercom.lisp (file)

Special Variable: *hydra-head-id*

represents the screen identifier of the current request

Package

intercom

Source

intercom.lisp (file)

Special Variable: *log-stream-lock*

this lock should be held when writing to the log stream.

Package

intercom

Source

intercom.lisp (file)

Special Variable: *remote-procedures*

contains all intercom remote procedures, the keywords being the matched string and the values being the corresponding function.

Package

intercom

Source

intercom.lisp (file)

Special Variable: *rid*

variable which contains the request id in functions which represent the execution of a remote procedure.

Package

intercom

Source

intercom.lisp (file)

5.2.2 Macros

Macro: assert-eql-compatible PLACE

asserts that place is an eql-compatible place. this means it must be one of:
1. a symbol
2. a character
3. a number

Package

intercom

Source

intercom.lisp (file)

Macro: assert-hydra-body PLACE

asserts that <place> contains a hydra-body

Package

intercom

Source

intercom.lisp (file)

Macro: assert-hydra-head PLACE

asserts that <place> contains a hydra-head

Package

intercom

Source

intercom.lisp (file)

Macro: assert-hydra-session-validation PLACE

asserts that <place> contains a hydra-session

Package

intercom

Source

intercom.lisp (file)

Macro: assert-nonempty-string PLACE

asserts that <place> contains a non-empty string.

Package

intercom

Source

intercom.lisp (file)

Macro: esc (ESCAPE-SYMBOL &key TEST RETURN) &body BODY

Package

intercom

Source

intercom.lisp (file)

Macro: in-intercom-session &body BODY

executes a hunchentoot request in an environment in which the special local variables are bound to be special and local.
this contains:
- *hydra-body*
- *hydra-head*
- *hydra-head-id*

Package

intercom

Source

intercom.lisp (file)

Macro: maybe-log-request &body BODY

executes <body> in an environment where the <log*> function is defined iff *log-request-stream* is non-nil. the <log*> function takes the type of content to log, followed by the content itself by &rest and it splices hydra-body-id hydra-head-id in that list.

Package

intercom

Source

intercom.lisp (file)

Macro: with-doublequotes (&rest VARIABLES) &body BODY

makes sure each variable in variables is bound to itself, essentially allowing you to write ,, in a double backtick to get that symbol. handy for gensym.

Package

intercom

Source

intercom.lisp (file)

Macro: with-hydra-auth-store-lock &body BODY

executes <body> in an environment in which *hydra-auth-store* is locked.

Package

intercom

Source

intercom.lisp (file)

Macro: with-key-value-store-lock STORE &body BODY

executes body in an environment in which <store> is locked.

Package

intercom

Source

intercom.lisp (file)

Macro: with-local-screen-lock (PROTECTION-SYMBOL) &body BODY

executes <body> in a piece of code in which the head’s data is locked

Package

intercom

Source

intercom.lisp (file)

5.2.3 Functions

Function: assert-session ()

asserts that we’re currently running in an environment which is sane for intercom requests/executions

Package

intercom

Source

intercom.lisp (file)

Function: attach-head HYDRA-BODY HYDRA-HEAD

attaches <hydra-head> to <hydra-body>

Package

intercom

Source

intercom.lisp (file)

Function: build-active-authentication HYDRA-BODY

builds a new authentication, which identifies hydra-body, and stores it in the necessary structures.

Package

intercom

Source

intercom.lisp (file)

Function: build-active-hydra-body ()

builds a new hydra-body and sets it as the current hydra-body.

Package

intercom

Source

intercom.lisp (file)

Function: call-remote-procedure RID NAME &rest ARGS

calls the remote prodecure with name <name> and <args> as the arguments with <rid> as reference. assumes the special variables *hydra-head* and *hydra-body* exist and respectively contain a hydra-head and a hydra-body.

Package

intercom

Source

intercom.lisp (file)

Function: close-request-logging REQUESTS

handles the logging of close requests

Package

intercom

Source

intercom.lisp (file)

Function: copy-hydra-body INSTANCE

Package

intercom

Source

intercom.lisp (file)

Function: copy-hydra-head INSTANCE

Package

intercom

Source

intercom.lisp (file)

Function: copy-key-value-store INSTANCE

Package

intercom

Source

intercom.lisp (file)

Function: copy-session-validation INSTANCE

Package

intercom

Source

intercom.lisp (file)

Function: discover-hydra ()

discover-hydra returns non-nil iff we had a session-cookie through which we could find a hydra session-validation which is valid for our current session. this function sets up all special variables for the hydra to be happy. it also touches the hydra-body and the relevant hydra-head so we’re active.

Package

intercom

Source

intercom.lisp (file)

Function: discover-hydra-body ()

returns non-nil iff we had a session-cookie through which we could find a hydra session-validation which is valid for our current session. this function sets up all special variables for the hydra-body,
but leaves the hydra-head for another solution to figure out.

Package

intercom

Source

intercom.lisp (file)

Function: ensure-hhid ()

returns the hhid if one was given as a get-variable, or creates a new hhid. does *not* put the hhid on the message stack.
returns (values hhid newp). if newp is t, a message should be sent to the client (see (send-current-hhid)) so the client knows the hhid.

Package

intercom

Source

intercom.lisp (file)

Function: ensure-hydra ()

ensures the hydra is set up. this means that:
- after this function execution:
- *hydra-head* is bound to the hydra’s head
- *hydra-body* is bound to the hydra’s body
- *hydra-auth-store* contains an authentication for continued storage - after this request:
- the user has a "hydra" cookie which links to this session.

Package

intercom

Source

intercom.lisp (file)

Function: ensure-hydra-head HYDRA-BODY

ensures the hydra-head exists and is set in the variable *hydra-head*. assumes *hydra-body* is set. returns the current hydra-head.

Package

intercom

Source

intercom.lisp (file)

Function: fetch-and-clear-messages ()

fetches and clears the messages in the mailbox

Package

intercom

Source

intercom.lisp (file)

Function: gc-hydra-bodies ()

garbage collect the head hydras. this removes the session-validation objects and removes the head heads.

Package

intercom

Source

intercom.lisp (file)

Function: gc-hydra-body HYDRA-BODY

garbage-collects a hydra-body

Package

intercom

Source

intercom.lisp (file)

Function: gc-hydra-head HYDRA-HEAD

garbage-collects a hydra-head

Package

intercom

Source

intercom.lisp (file)

Function: gc-hydra-heads HYDRA-BODY

detaches the dead heads from <hydra-body>.

Package

intercom

Source

intercom.lisp (file)

Function: generate-id ()

we generate an id by taking the universal time and augmenting it by some random number

Package

intercom

Source

intercom.lisp (file)

Function: get-remote-procedure NAME

returns the remote procedure for <name> or nil if the procedure doesn’t exist.

Package

intercom

Source

intercom.lisp (file)

Function: hash-keys HASH

returns a list of all hash-keys in <hash>

Package

intercom

Source

intercom.lisp (file)

Function: hydra-body-active-p HYDRA

returns non-nil iff the <hydra> hasn’t been touched for too long of a time.

Package

intercom

Source

intercom.lisp (file)

Function: hydra-body-atime INSTANCE

Function: (setf hydra-body-atime) VALUE INSTANCE

Package

intercom

Source

intercom.lisp (file)

Function: hydra-body-data INSTANCE

Function: (setf hydra-body-data) VALUE INSTANCE

Package

intercom

Source

intercom.lisp (file)

Function: hydra-body-garbage-collected-body-p INSTANCE

Function: (setf hydra-body-garbage-collected-body-p) VALUE INSTANCE

Package

intercom

Source

intercom.lisp (file)

Function: hydra-body-gc-callbacks INSTANCE

Function: (setf hydra-body-gc-callbacks) VALUE INSTANCE

Package

intercom

Source

intercom.lisp (file)

Function: hydra-body-heads INSTANCE

Function: (setf hydra-body-heads) VALUE INSTANCE

Package

intercom

Source

intercom.lisp (file)

Function: hydra-body-p OBJECT

Package

intercom

Source

intercom.lisp (file)

Function: hydra-head-active-p HYDRA

returns non-nil iff the <hydra> hasn’t been touched for too long of a time.

Package

intercom

Source

intercom.lisp (file)

Function: hydra-head-atime INSTANCE

Function: (setf hydra-head-atime) VALUE INSTANCE

Package

intercom

Source

intercom.lisp (file)

Function: hydra-head-data INSTANCE

Function: (setf hydra-head-data) VALUE INSTANCE

Package

intercom

Source

intercom.lisp (file)

Function: hydra-head-garbage-collected-body-p INSTANCE

Function: (setf hydra-head-garbage-collected-body-p) VALUE INSTANCE

Package

intercom

Source

intercom.lisp (file)

Function: hydra-head-gc-callbacks INSTANCE

Function: (setf hydra-head-gc-callbacks) VALUE INSTANCE

Package

intercom

Source

intercom.lisp (file)

Function: hydra-head-id INSTANCE

Function: (setf hydra-head-id) VALUE INSTANCE

Package

intercom

Source

intercom.lisp (file)

Function: hydra-head-p OBJECT

Package

intercom

Source

intercom.lisp (file)

Function: in-active-remote-procedure-p ()

returns non-nil if we are currently in a remote procedure with an active rid.

Package

intercom

Source

intercom.lisp (file)

Function: key-value-store-hash INSTANCE

Function: (setf key-value-store-hash) VALUE INSTANCE

Package

intercom

Source

intercom.lisp (file)

Function: key-value-store-lock INSTANCE

Function: (setf key-value-store-lock) VALUE INSTANCE

Package

intercom

Source

intercom.lisp (file)

Function: key-value-store-p OBJECT

Package

intercom

Source

intercom.lisp (file)

Function: kv-store-read KEY STORE

reads the key from store

Package

intercom

Source

intercom.lisp (file)

Writer

(setf kv-store-read) (function)

Function: (setf kv-store-read) VALUE KEY STORE

sets <key> in <store> to <value>

Package

intercom

Source

intercom.lisp (file)

Reader

kv-store-read (function)

Function: make-hydra-body &key (DATA DATA) (ATIME ATIME) (HEADS HEADS) (GC-CALLBACKS GC-CALLBACKS) (GARBAGE-COLLECTED-BODY-P GARBAGE-COLLECTED-BODY-P)

Package

intercom

Source

intercom.lisp (file)

Function: make-hydra-head &key (ID ID) (DATA DATA) (ATIME ATIME) (GC-CALLBACKS GC-CALLBACKS) (GARBAGE-COLLECTED-BODY-P GARBAGE-COLLECTED-BODY-P)

Package

intercom

Source

intercom.lisp (file)

Function: make-key-value-store &key (LOCK LOCK) (HASH HASH)

Package

intercom

Source

intercom.lisp (file)

Function: make-log-message-string TYPE &rest ARGS

constructs a log message string for type and the followed arguments.

Package

intercom

Source

intercom.lisp (file)

Function: make-remote-procedure-lambda-function ARGUMENTS BODY

builds the s-expression representation for the lambda function which can be called for the definition of a remote procedure. this handles the creation of the &key arguments.

Package

intercom

Source

intercom.lisp (file)

Function: make-session-validation HYDRA-BODY COOKIE-IDENTIFIER

constructs a new session-validation object for the current session.

Package

intercom

Source

intercom.lisp (file)

Function: mk-session-validation &key (HYDRA-ID HYDRA-ID) (HOST HOST) (USER-AGENT USER-AGENT) (HYDRA-BODY HYDRA-BODY)

Package

intercom

Source

intercom.lisp (file)

Function: perform-close-request RID

closes the request for the rid.

Package

intercom

Source

intercom.lisp (file)

Function: perform-intercom-request JSOWN-REQUEST

performs an intercom request as described by <jsown-request>.

Package

intercom

Source

intercom.lisp (file)

Function: ping-logging ()

handles the logging of the ping request

Package

intercom

Source

intercom.lisp (file)

Function: register-remote-procedure NAME FUNCTION

registers the remote procedure for <name> to be <function>.

Package

intercom

Source

intercom.lisp (file)

Function: remove-hydra-validation SESSION-VALIDATION

removes the session-validation <session-validation> from the known validations.

Package

intercom

Source

intercom.lisp (file)

Function: remove-rid RID

removes the <rid> from the list of active rids

Package

intercom

Source

intercom.lisp (file)

Function: request-logging REQUESTS

handles the logging of the new requests

Package

intercom

Source

intercom.lisp (file)

Function: response-logging RESPONSES

handles the logging of the responses

Package

intercom

Source

intercom.lisp (file)

Function: retrieve-hydra-validations HYDRA-ID

returns all hydra session-varlidation instance which belong to the given hydra-id

Package

intercom

Source

intercom.lisp (file)

Function: rid-active-p RID &optional MY-ACTIVE-RIDS

returns non-nil iff <rid> is active for the current user. by use of the variable my-active-rids, the currently active rids can be overridden. !only use when you know what you’re doing!

Package

intercom

Source

intercom.lisp (file)

Function: s+ &rest ARGS

pretty-prints and concatenates the resulting strings of each arg in <args>.

Package

intercom

Source

intercom.lisp (file)

Function: send-current-hhid ()

sends the current hhid to the client by using the correct intercom message. requires that *hydra-head* and *hydra-head-id* are set correctly.

Package

intercom

Source

intercom.lisp (file)

Function: session-validation-host INSTANCE

Function: (setf session-validation-host) VALUE INSTANCE

Package

intercom

Source

intercom.lisp (file)

Function: session-validation-hydra-body INSTANCE

Function: (setf session-validation-hydra-body) VALUE INSTANCE

Package

intercom

Source

intercom.lisp (file)

Function: session-validation-hydra-id INSTANCE

Function: (setf session-validation-hydra-id) VALUE INSTANCE

Package

intercom

Source

intercom.lisp (file)

Function: session-validation-p OBJECT

Package

intercom

Source

intercom.lisp (file)

Function: session-validation-user-agent INSTANCE

Function: (setf session-validation-user-agent) VALUE INSTANCE

Package

intercom

Source

intercom.lisp (file)

Function: start-rid RID

sets <rid> to be active

Package

intercom

Source

intercom.lisp (file)

Function: store-hydra-validation SESSION-VALIDATION

stores the hydra session-validation so it can be found back.

Package

intercom

Source

intercom.lisp (file)

Function: talk &key

Package

intercom

Source

intercom.lisp (file)

Function: thread-initial-bindings ()

calculates the initial bindings for the current thread. this consists of whatever is available in bordeaux-threads:*initial-bindings*, but with what *remote-procedure* contains in front of it (in which the values are evaluated).

Package

intercom

Source

intercom.lisp (file)

Function: valid-session-p SESSION-VALIDATION COOKIE-IDENTIFIER

validates the session-validation for the current request

Package

intercom

Source

intercom.lisp (file)

5.2.4 Generic functions

Generic Function: touch OBJECT

touches an object, updating the modification time.

Package

intercom

Source

intercom.lisp (file)

Methods

Method: touch (HYDRA hydra-head)

Method: touch (HYDRA hydra-body)

5.2.5 Structures

Structure: hydra-body ()

Package

intercom

Source

intercom.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods

touch (method)

Direct slots

Slot: data

Initform

(intercom::make-key-value-store)

Readers

hydra-body-data (function)

Writers

(setf hydra-body-data) (function)

Slot: atime

Initform

(get-universal-time)

Readers

hydra-body-atime (function)

Writers

(setf hydra-body-atime) (function)

Slot: heads

Readers

hydra-body-heads (function)

Writers

(setf hydra-body-heads) (function)

Slot: gc-callbacks

Readers

hydra-body-gc-callbacks (function)

Writers

(setf hydra-body-gc-callbacks) (function)

Slot: garbage-collected-body-p

Readers

hydra-body-garbage-collected-body-p (function)

Writers

(setf hydra-body-garbage-collected-body-p) (function)

Structure: hydra-head ()

Package

intercom

Source

intercom.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods

touch (method)

Direct slots

Slot: id

Readers

hydra-head-id (function)

Writers

(setf hydra-head-id) (function)

Slot: data

Initform

(intercom::make-key-value-store)

Readers

hydra-head-data (function)

Writers

(setf hydra-head-data) (function)

Slot: atime

Initform

(get-universal-time)

Readers

hydra-head-atime (function)

Writers

(setf hydra-head-atime) (function)

Slot: gc-callbacks

Readers

hydra-head-gc-callbacks (function)

Writers

(setf hydra-head-gc-callbacks) (function)

Slot: garbage-collected-body-p

Readers

hydra-head-garbage-collected-body-p (function)

Writers

(setf hydra-head-garbage-collected-body-p) (function)

Structure: key-value-store ()

Package

intercom

Source

intercom.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots

Slot: lock

Initform

(bordeaux-threads:make-recursive-lock "key-value-lock")

Readers

key-value-store-lock (function)

Writers

(setf key-value-store-lock) (function)

Slot: hash

Initform

(make-hash-table)

Readers

key-value-store-hash (function)

Writers

(setf key-value-store-hash) (function)

Structure: session-validation ()

Package

intercom

Source

intercom.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots

Slot: hydra-id

Type

string

Initform

""

Readers

session-validation-hydra-id (function)

Writers

(setf session-validation-hydra-id) (function)

Slot: host

Type

string

Initform

""

Readers

session-validation-host (function)

Writers

(setf session-validation-host) (function)

Slot: user-agent

Type

string

Initform

""

Readers

session-validation-user-agent (function)

Writers

(setf session-validation-user-agent) (function)

Slot: hydra-body

Type

(or intercom::hydra-body null)

Readers

session-validation-hydra-body (function)

Writers

(setf session-validation-hydra-body) (function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types