The Client View of the Context-User-Item Model
The Session Object
When a client first establishes a connection to a Context Server, there is
one server object in scope that it can send messages to. This is the Session
object, which represents the session connection itself. The Session object is
always known by the ref "session"
.
The client may send the following messages to the server presence of the Session object:
entercontext
→ { to:"session", op:"entercontext",
context:CTXREF_STR,
user:?USERREF_STR,
name:?STR,
sess:?STR,
auth:?STR,
debug:?BOOL }
This message places (or attempts to place) a user into a particular context on the server.
context
is the ref of the context into which the user is seeking entry.user
is the ref of the user as whom the client is attempting to enter. Whether this parameter is required or not depends on the context.name
is a name string to present for the user in the application user interface, particularly to other users. This parameter is usually only applicable when theuser
parameter is omitted. If bothuser
andname
are omitted, the default name is"<anonymous>"
.sess
is an optional client-in-context session identifier string, enabling the client to associate a particular context entry notification with a particularentercontext
request. If this parameter is given in theentercontext
request, a correspondingsess
parameter will be provided in themake
message that the server sends to the client to create the client presence of the context object.auth
is an authorization string that may be required to gain entry into the context. If the context is a password-protected context, this string must be the correct password. If the context is a reservation-controlled context, this string must be the reservation token that was issued by the Director.debug
is an optional flag that configures the session for debugging if the server is configured to permit this. The main effect of this is to increase some of the timeouts when communicating over HTTP, so that a developer who is composing requests manually using something like Telnet won't be disconnected because they type too slowly.
"make"
messages describing the context and the users and items it
contains, including a description of the entering user. This series of
"make"
messages will be terminated by a "ready"
message targeted at the context, after which the client may consider itself to
be fully entered into the context. In particular, after that point, the server
may send additional, unsolicited messages to the client describing changes in
the context environment and activity going on there. The nature of these
messages depends on the specific application that the context is presenting.
Note that a user may be entered into more than one context concurrently.
The user's presence in any particular context will be identified by a unique
context-specific reference string that will be provided as part of the user
description sent to the client in response to the "entercontext"
message. Messages sent from the server to the client will use this reference
string as the message target for messages to the user, allowing the client to
disambiguate which presence (and thus which application) the message pertains
to.
disconnect
→ { to:"session", op:"disconnect" }
This message removes the user from any contexts they are in and terminates the session. The connection to the server is broken.
ping
→ { to:"session", op:"ping", tag:?STR }
This message tests connectivity to the server.
tag
is an optional string that may be anything of the client's choosing.
If the message is successfully received by the server, it will reply with:
← { to:"session", op:"pong", tag:?STR }
tag
echoes the tag from theping
message, if there was one, or will be omitted if the originalping
also omitted it.
debug
→ { to:"session", op:"debug", msg:STR }
This message delivers debugging information to the server. If the server is
configured to permit this, the string given in the msg
parameter
will be written to the server's log. If the server is not configured to permit
this, this message will simply be ignored.
The server may send the following messages to the client presence of the Session object:
make
The server will send "make"
messages to the session to direct
it to create client presences of context objects (within a context, successive
"make"
messages will be directed to the context object itself to
generate the in-context user object and the other objects contained by the
context). The "make"
message is generic. It is described below.
exit
← { to:"session", op:"exit",
why:?STR,
whycode:STR,
reload:?BOOL }
This message informs the client that it is being disconnected from the
server. After this message is sent, the server will close the connection.
This may be sent in reply to a "disconnect"
message sent by the
client to the server, but it may also be sent spontaneously as a result of
events happening on the server.
why
is an optional debug string that describes the reason for the disconnection.whycode
is a machine-readable tag string that indicates the reason for the disconnection.reload
is an optional flag (if omitted, defaults to false) that, if true, directs the client to immediately attempt another entry to the same context. If the context was entered by obtaining a reservation from a Director, the client should first obtain a new reservation.
The possible values for whycode
and what they mean:
"shutdown" |
server is shutting down |
"dupentry" |
you were already here |
"full" |
context is full |
"nores" |
you needed a reservation and didn't provide one |
"badres" |
your reservation was expired or no good |
"baduser" |
invalid user ref, invalid or missing user record, or unable to determine user from uparam parameters |
"badcontext" |
invalid context ref, or invalid or missing context record |
"timeout" |
you took too long before sending entercontext |
"nodir" |
no director available (for push) |
"admin" |
administrative eviction |
"dirdeny" |
director denied reservation (for push) |
"dirfail" |
director failed (for push) |
"contextclose" |
context is shutting down |
"restricted" |
entry to context is restricted |
"noanonymity" |
context does not allow anonymous users |
"gateclosed" |
context is closed to entry for application-specific reasons |
"bye" |
you exited normally on purpose |
Generic messages
The server may send the following messages to any C-U-I object:
make
← { to:CONTAINERREF_STR, op:"make",
maker:?USERREF_STR,
obj:OBJDESC,
you:?BOOL,
sess:?STR }
This message directs the client to create a client presence of a C-U-I
object. The target of the message is the container into which the object
should be created. If this container is "session"
, then the new
object will be "contained" by the session; as a rule, the only objects that
will be belong to the session in this way are the contexts themselves. Users
will be contained by context objects, while items may be contained by contexts,
by users, or by other items.
maker
is an optional indicator of the user who is triggering the creation of the object. Normally, this parameter will be omitted, in which case the object is presumed to be created by the system itself. However, this parameter may appear if an object (normally an item) is being created as the consequence of a particular user's actions in the context.obj
is a JSON literal describing the object to be created. These are documented in more detail below.you
is an optional flag that, if true (defaults to false if omitted), indicates that the object being created represents the user of the client receiving the message.sess
is an optional client-in-context session identifier string. This parameter will only be present when a context object is being created, and then only if there was asess
parameter provided in theentercontext
message that led to this context creation event. The value will echo the value from theentercontext
message, enabling the client to match themake
message with its originalentercontext
request.
delete
← { to:REF_STR, op:"delete" }
This message directs the client to delete its client presence of the C-U-I object that is the target of the message, as well as any other objects it may contain. After this message is received, the targeted object no longer exists in the context environment, and messages sent to the server presence of the object will be rejected by the server.
say
← { to:REF_STR, op:"say",
from:?USERREF_STR,
text:STR }
This message is used to carry system messages and text chat. It directs the client to display the text string that was transmitted, in a manner consistent with the application in the context. The target of this message is always the context or a user, never an item. If targeted at a user, the communication is for that user. If targeted at the context, it is for all users in the context. (Note that a given client will only receive messages targeted at its own user or at the context.)
from
, if given, is the ref of (another) user who is represented by the server as the source of the message. If omitted, the message is considered to come from the server itself.text
is the message being spoken.
push
← { to:REF_STR, op:"push",
from:?USERREF_STR,
url:STR,
frame:?STR }
This message directs the client to load a web page. The target of this message is always the context or a user, never an item. If targeted at a user, the intent is that that user is being pushed to the given URL. If targeted at the context, all users in the context are being pushed. (Note that a given client will only receive messages targeted at its own user or at the context.)
from
, if given, is the ref of (another) user who is represented by the server as the source of the push. If omitted, it is considered to come from the server itself.url
is the URL to load.frame
, if given, names the browser HTML frame into which the URL is to be loaded. If omitted, the URL should be loaded as an entirely new page.
The Context Object
When a context is created by a "make"
message, the
obj
parameter of the "make"
message will be a context
descriptor, which is a JSON object of the form:
{ type:"context", id:CTXREF_STR,
name:STR,
mods:[MODDESC] }
id
is the reference string for the new context.name
is the context's printable name, which may be significant in the application user interface.mods
, if present, is an array of mods attached to the context. Each of these is a JSON object describing a particular mod. The form of these mod descriptors varies depending on what kind of mods they are. The current set of supported mods is described here.
Upon successful entry to a context (such as when the client sends an
entercontext
message to the server presence of the session
object), the server will send a "make"
message to the client
presence of the session object, creating the client presence of the context
itself. This context object will then be sent one or more "make"
messages creating client presences for the other users in the context and for
any items contained by the context. If any of these users or items have any
contents of their own, additional "make"
messages will be sent to
those objects that create their content objects. The end of this series
of "make"
messages will be indicated by the server sending a
"ready"
message to the context. Finally, the server will send the
context a "make"
message creating the client presence of user who
entered.
ready
← { to:CTXREF_STR, op:"ready" }
This message signals to the client that the series of "make"
messages generating the context and its contents is complete and that the
context is ready for the client to interact with it.
exit
→ { to:CONTEXT_REF, op:"exit" }
This message removes the sending user from the context and terminates their interaction with it.
The context object may understand additional messages depending on what mods are attached to it.
The User Object
When a user is created by a "make"
message, the
obj
parameter of the "make"
message will be a user
descriptor, which is a JSON object of the form:
{ type:"user", id:USERREF_STR,
name:STR,
mods:[MODDESC] }
id
is the reference string for the new user.name
is the user's printable name.mods
, if present, is an array of mods attached to the user. Each of these is a JSON object describing a particular mod. The form of these mod descriptors varies depending on what kind of mods they are. The current set of supported mods is described here.
The Item Object
When an item is created by a "make"
message, the
obj
parameter of the "make"
message will be an item
descriptor, which is a JSON object of the form:
{ type:"item",
id:ITEMREF_STR,
name:STR,
mods:[MODDESC],
cont:?BOOL,
deletable:?BOOL }
id
is the reference string for the new item.name
is the item's printable name.mods
, if present, is an array of mods attached to the item. Each of these is a JSON object describing a particular mod. The form of these mod descriptors varies depending on what kind of mods they are. The current set of supported mods is described here.cont
is a flag that, if true, indicates that the item may be used as a container (i.e., it may contain other items, even if it does not currently do so). If omitted, it should be treated as false.deletable
is a flag that, if true, indicates that the item may be deleted by ordinary users by sending it a"delete"
message. If omitted, it should be treated as false.
delete
→ { to:ITEMREF_STR, op:"delete" }
A client may request the server to delete a deletable item by sending a
"delete"
message targeted at the item it wishes to delete. If the
server complies, it will send a delete message back (see Generic Messages above) directing the client to go
ahead and delete the item.