COLLABSRV(8)COLLABSRV(8)NAMEcollabsrv - multi-user collaboration
SYNOPSIS
collab/collabsrv [ -f keyfile ] [ -n netaddress ] [ dir ]
collab/servers/chatsrv
collab/servers/mpx
collab/servers/wbsrv
DESCRIPTION
Collabsrv listens on network address netaddress (default: tcp!*!9999)
for incoming requests to attach to services it offers. The services
are defined by the contents of directory dir (default: /services/col‐
lab). Collabsrv serves an authenticated 9P connection that exports the
contents of dir/export (default: /services/collab/export). The
exported name space can contain directories from a shared file server,
but it will also contain a directory services giving access to any col‐
laborative activity services that have been configured.
The services directory contains a single ctl file and a set of subdi‐
rectories, numbered 0, 1 and so on. The ctl is used to activate and
access services. Each service instance is identified by a name;
clients connect to a given instance by presenting its name. Each
directory represents one instance of a service. Each service instance
corresponds to a name space; the clients all share that name space.
The name space is determined by the service.
A client wishing to make use of the services must first dial(2) to con‐
nect to collabsrv, and authenticate and mount the resulting 9P connec‐
tion. It can do so using the mount command (see bind(1)), or by using
security-auth(2) and Sys->mount (see sys-bind(2)). Normally, this is
done by collab(1).
A new connection to a particular service is requested by opening the
ctl file for reading and writing, writing a service request to it, and
reading back the number of the directory corresponding to the requested
service. A service request written to ctl is text of the following
form:
service id
where service is a string specifying the type of service (eg, chat) and
id is a string identifying the instance. The server does not interpret
id; it is up to the clients to agree a naming convention (often using
the name of a shared file as an id). Collabsrv will connect to
instance id of the requested service type if one is already running, or
start one if necessary; the write request returns an error if the ser‐
vice cannot be started. Following a successful write to ctl, a read
will return the number of the service directory containing the client's
private connection to that service instance. Closing the ctl file dis‐
connects from the service.
Available services are defined by a configuration file /services/col‐
lab/services.cfg, which contains a sequence of configuration entries of
the following form:
service
path=disfile
where service is the name presented in a service request, and disfile
names a Dis file implementing that service; path names are interpreted
relative to /services/collab, but usually refer to files in /dis/col‐
lab/servers.
Each collabsrv service is represented by a name space peculiar to that
service. The interface to the service is therefore implemented by a
service-specific 9P server (disfile in the configuration file). Cur‐
rent services are described below.
Chat
Chatsrv provides a simple service for the exchange of text messages.
It serves a name space containing two files. The files together repre‐
sent a single messaging group:
users A read-only file that lists the user names of the current mem‐
bers of the group, one per line. The version number of the
file's Qid (see sys-stat(2)) is incremented each time a client
arrives or leaves.
msgs
A client connects to the messaging group by opening this file.
A message is sent to the group by writing to the file. Each
read returns the next unread message, prefixed by the name of
the sender, or <you> for a message sent by the current client.
A client sees no messages sent before it connects. Messages are
delivered in the same order to all clients; clients receive
their own messages. Two special messages are generated by the
server:
+++ name has arrived
--- name has left
as clients come and go.
Multiplexor
Mpx offers a general fan-out/fan-in multiplexing service for a tree of
processes, with one controlling or root process at the root of the
tree, and a set of client processes at the leaves of the tree. It
serves three files:
root An exclusive-use file read and written by the root process to
communicate with the leaf processes.
leaf Client processes read and write this file to communicate with
the root process (each open of leaf is independent). It cannot
be opened until a process has opened root. After root has been
closed, and any remaining messages on leaf have been read, sub‐
sequent reads will return zero bytes (end-of-file).
users A read-only text file that lists the user names of processes
that currently have leaf open. There is one line per leaf, con‐
taining a unique numeric ID for the leaf, a space, and then the
users's name.
A message written to root is replicated on all instances of leaf that
are currently open. A message written to any instance of leaf will be
read by the process reading root. Data written to both root and leaf
has a prefix added to identify the sender, causing messages to have the
following format:
seq clientid op name data
where seq is a unique message sequence number; clientid is a unique
number identifying the process amongst currently connected clients,
with 0 identifying the root process; op is a single character giving
the message type (see below); name is the sending process's user name;
and data is the data written by the process, which can be text or
binary (the message header is always text). Mpx also generates mes‐
sages as root and leaf processes arrive and leave. These are identi‐
fied by op. The various op values and the direction in which they can
occur are listed below:
a New leaf process has arrived (leaf to root)
M Message from root process (root to leaf)
m Message from leaf process (leaf to root)
L Root process has left (root to leaf)
l Leaf process has left (leaf to root)
Messages are only ever sent from the root to all leaves, or from a leaf
to the root, never from leaf to leaf; the root process could of course
rebroadcast a message from a leaf. The multiplexor service is used to
implement a real-time poll (see poll and poller in collab-clients(1)),
but could be used for several other services, such as auctions.
Whiteboard
Wbsrv offers a service for sharing a simple line drawing. It serves
two files:
wb.bit A read-only file containing an uncompressed image(6) with the
current state of the drawing.
strokes
This file is read and written to exchange strokes with other
clients. A stroke has the following representation:
colour width x0 y0 x1 y1 ...
where all values are space-separated decimal numbers: colour is
an index into the rgbv(6) colour map; width is the width of the
line in pixels, and the sequence of coordinate pairs defines the
connected line segments to draw. A stroke is transmitted from
one client to all others by writing a stroke description to the
file in a single write. Each read returns a description of a
stroke made by another client.
A whiteboard client should read the wb.bit file to obtain its image,
then read the strokes file for instructions to keep it up to date.
FILES
/services/collab/export/services
active service directory
/services/collab/services.cfg
maps service names to modules
/dis/collab/servers
service implementation modules
SOURCE
/appl/collabsrv
/appl/collab/servers
/appl/collab/lib
SEE ALSOcollab(1), collab-clients(1)COLLABSRV(8)
