INTERNET-DRAFT Mark Day
Expires: July 21, 1998 Lotus Development Corporation
Simple General Awareness Protocol (SGAP)
draft-day-sgap-00.txt
1. Status of this Memo
This document is an Internet-Draft. Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its
areas, and its working groups. Note that other groups may also
distribute working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by other
documents at any time. It is inappropriate to use Internet-
Drafts as reference material or to cite them other than as
"work in progress."
To view the entire list of current Internet-Drafts, please check
the "1id-abstracts.txt" listing contained in the Internet-Drafts
Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net
(Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East
Coast), or ftp.isi.edu (US West Coast).
2. Abstract
The Simple General Awareness Protocol (SGAP) provides notifications of
changes to small data items. The changes are selectively made
available to a large collection of viewers. This facility is most
useful for a class of applications variously called people locators,
colleague-awareness tools, people browsers, or ''buddy lists''.
3. Contents
1. Status of this Memo
2. Abstract
3. Contents
4. Introduction
5. Properties
6. Protocol Model
7. Server-Server Protocol Not a Special Case
8. Special Server Behavior
9. Protocol Specification
9.1 Model
9.2 Summary of Messages
9.3 Body Encoding
9.3.1 Types
9.4 Messages
9.4.1 Declare
9.4.2 Create
9.4.3 Modify
9.4.4 Delete
9.4.5 Split Viewers
9.4.6 Merge Viewers
9.4.7 List Viewers
9.4.8 Viewer List
9.4.9 Fetch
9.4.10 Fetch Response
9.4.11 Enable
9.4.12 Disable
9.4.13 Creation
9.4.14 Modification
9.4.15 Deletion
9.4.16 OK
9.4.17 Error
10. Acknowledgements
11. References
4. Introduction
Synchronous collaboration in a network environment is determined by
the characteristics of people and how they work together. We have
found it useful to divide synchronous collaboration into three phases:
awareness, conversation, and sharing. A collaboration proceeds
through the phases in that order. Multiple overlapping and returning
sequences through this model are possible
i. Awareness: A user first becomes aware that other users, groups, or
resources of interest are available. Awareness is comparable to the
function of peripheral vision.
ii. Conversation: Having become aware of those others, the user starts
one or more conversations or conferences with those people (via
various media, such as voice, text, or video).
iii. Sharing: Being engaged in conversations, the user finds it useful
to share documents or other objects. Such sharing adds value in two
ways. First, it allows for richer collaboration than is possible with
conversation alone, such as jointly editing a document or playing a
real-time game. Second, it allows for conversational ellipsis: for
example, a gesture at a sentence accompanied by the phrase "I don't
like this" instead of "I don't like the sentence halfway down page 3
that starts with 'Synchronous.'"
The Simple General Awareness Protocol (SGAP) is intended to be used
primarily for awareness, the first phase of the process. SGAP is not
intended as a mechanism for conversation or sharing; there are a
number of technologies that can be used for various forms of
conversation and sharing, and relatively few that allow for the
features required of an awareness system.
In addition, the requirements in the two contexts are fundamentally
different. An awareness system involves the selective exposure of
small amounts of information to large numbers of others, with
relatively loose consraints on latency. A conversation and sharing
system involves the sharing of large amounts of information
(high-bandwidth channels) among a relatively small group, with
relatively tight constraints on latency. To use a telephone-system
analogy, we consider awareness to be largely "signalling" for the
higher-bandwidth "connection" represented by the conversations and
sharing.
5. Properties
A property is the smallest of these units. A property consists of a
name, a type, and a value. Both the name and type of a property are
UTF-8 encoded text strings, with relatively few restrictions on the
form of the strings. A property's value is zero or more bytes of
arbitrary data. Architecturally, a value may be up to 4 gigabytes, but
servers may set a smaller bound on the size of values. A server MUST
NOT break the connection only because a client sends an
excessively-large value. Instead, the server must send an error
message, then count bytes past the offending element and continue with
the next usable request.
6. Protocol Model
Conceptually, a server implements a matrix, with a row for each
distinct item to be shared and a column for each distinct viewer with
whom that information should be shared. The intersection of a column
and row is called a cell, and corresponds to the view of an item
delivered to a viewer.
Each item has a distinct item name. The item name is used simply as an
identifier for the item; in general, there are no additional semantics
(however, a small number of item names are significant to the
server). For example, "www.lotus.com" is different from
"http://www.lotus.com", though both are legal item names, as is any
UTF-8 encoded string of non-zero length (such as "Bill Clinton" or
"X%66 52 *$#").
Each viewer also has a distinct viewer name. Again, the viewer name is
used simply as an identifier for the viewer; in general, there are no
additional semantics (again, a small number of viewer names are
significant to the server).
Although distinct items have distinct names, and distinct viewers have
distinct names, it is acceptable for an item and a viewer to have the
same name. Indeed, such name-sharing is the typical case.
The protocol assumes an authenticated connection between client and
server. The authenticated client entity is referred to as the
principal.
A client declares its use of a given name. Usually, such a declaration
means that the client both acts as the item with that name, and acts
as the viewer with that name; however, a client may optionally decline
one of the roles when it declares a name. The server may refuse to
allow a given principal to declare particular names, or may limit the
number of names that a given principal may declare, or may require
that a given principal use one of a restricted set of names.
A client declared as a given item can affect (change the properties
of) the row corresponding to that item. A client can only affect a row
if it has declared itself as that item. A client declared as a given
viewer can see (get the values of) the column corresponding to that
viewer. A client can only see a column if it has declared itself as
that viewer.
A client may enable or disable notifications on any item that it can
see. When notifications are enabled on an item, any change in the
properties of that item cause a notification message to be sent to
that client.
There is a special viewer column representing the default viewer. This
column does not have an associated viewer name, and accordingly can
never be directly accessed by a viewer. However, a client declared as
an item can determine which properties are in the default column for
that item, as well as determining which viewer names actually map to
the default column for that item.
The default-viewer column allows the possibility of both
default-accessible and default-inaccessible sharing of
information. For a default-accessible item, the item's value appears
in the default column's cell. Viewers to be excluded are named
explicitly, with no value (or substitute values) appearing in the
cells of those columns. For a default-inaccessible item, no value
appears in the default column's cell. Viewers who can access the item
are named explicitly, with the appropriate value appearing in the
cells.
A single client-to-server transport connection can carry out commands
on behalf of an arbitrary number of items and viewers. In the case of
a "buddy list," the expected behavior is to act on behalf of a single
item and a single viewer, both representing the person using the
client.
7. Server-Server Protocol Not a Special Case
Multiple servers can coordinate their state using the existing
protocol. The protocol allows both a "publish" model and a "subscribe"
model, favoring neither over the other.
Consider a server P that has some items (x,y,z) being updated by
clients. To "publish" those items and make them available to Q's
clients, P connects to another server Q and declares the names
(x,y,z). From Q's perspective, P is just another client (although P's
authentication to Q likely establishes that P's principal has more
privileges than the typical client).
Correspondingly, to "subscribe" to those items, a third server R can
connect to P and declare the names (x,y,z), choosing to be only in the
viewer role on those names.
Although SGAP supports the publication or subscription of items across
multiple servers, the protocol does not specify how clients or servers
arrange for such publication or subscription to take place. Note that
there is no mechanism in the protocol that would either prevent or
detect a request loop among servers.
8. Special Server Behavior
Some properties provide information to the server about how to treat
an item. For example, some items should be deleted if the reponsible
client is disconnected, while others should persist; this difference
in behavior is encoded in one or more special properties understood by
the server.
The properties understood by a server are collectively called the
server schema. Server schemas are defined independently of the
protocol. However, the mechanism to determine the schema of a server
is fixed by the protocol.
The server schema of a given server is exposed as the item
named "SGAP:Schema-Root". Within that item, the properties named
"SchemaName" and "SchemaVersionNumber" are guaranteed to be
defined. The value of SchemaName is a UTF-8 encoded text string. The
value of SchemaVersionNumber is a 4-byte array, representing an
unsigned integer in network order.
9. Protocol Specification
9.1 Model
We consider an awareness service to be a map:
context X viewer name X item name -> property*
That is, for each triplet of <context,viewer name,item name>, there is
a collection of zero or more properties.
9.2 Summary of Messages
In general, messages are carried via a reliable bytestream transport,
such as TCP. The following table summarizes the protocol messages and
their function.
Message Meaning
Declare Claim right to act on behalf of viewers
and/or items
Create Create new properties of an item exposed
to a viewer
Modify Modify the properties of an item exposed to
a viewer
Delete Delete the properties of an item exposed to
a viewer
Split Viewers Inform server that these viewers should see a
private (non-default) view of the item
Merge Viewers Inform server that these viewers should see the
default view of the item
List Viewers Get the names of viewers with private views
of an item
Viewer List Reply containing the names of viewers with
private views of an item
Fetch Get the properties provided to a viewer for
a set of items
Fetch Reponse Reply containing the properties for a set
of items
Enable Allow delivery of change notifications
Disable Suppress delivery of change notifications
Creation Notify of property creation
Modification Notify of property modification
Deletion Notify of property deletion
OK Acknowledge successful completion
Error Explain an error condition
The header of each message consists of a one-byte version number, a
one-byte opcode, one reserved byte, one default-flag byte, and a
4-byte length (in network order) of the following body in bytes, not
including the header or length itself.
+--------------+--------------+--------------+--------------+
| 0x05 | opcode | 0x00 | default-flag |
+--------------+--------------+--------------+--------------+
| length in bytes of following body |
+-----------------------------------------------------------+
| body |
+ . +
| . |
+ . +
The version number MUST be set to 0x05 in this version of the protocol.
The opcode identifies the operation to be carried out in response to
the message.
The reserved byte MUST be set to 0x00 in this version of the protocol
and MUST be ignored by implementations.
The default-flag byte is used to indicate whether an operation applies
to the default cell(s) and/or all other cell(s). The flag is needed
because the default cells have no name: they correspond to every
viewer for which the server does not have a viewer-specific cell. In
addition, there is no way to name "all viewers other than default."
The following table lists the acceptable values for the default-flag
byte and their interpretation.
0x00 All viewer cells to which the operation applies are explicitly
named in the body.
0x01 The default viewer cell(s) are affected in addition to any cells
explicitly named in the body.
0x02 All cells except the default viewer cell(s) are affected.
0x03 All cells of the item(s) are affected.
No other values are legal. That is, the two low-order bits serve as
flags, and the other bits MUST be zero.
The default-flag byte is only used for a few message types, but there
would be no advantage to putting its flags into the body of those
messages. Neither the version number nor the opcode requires more
than a single byte, while it is advantageous for some machines to have
the 4-byte length aligned on a 4-byte boundary. So the default-flag
byte uses a byte that would otherwise be "wasted" in the header.
9.3 Body Encoding
A "vector" is encoded as a 4-byte unsigned integer in network order,
followed by the number of elements determined by that integer's value,
followed by 0 to 3 padding bytes. The number of padding bytes is
chosen so that the entire vector's length in bytes is a multiple of
4. Padding bytes are chosen to alternate between the values 0xAC and
0xDC. Implementations MUST ignore the value of padding bytes received.
A "String" is a vector of bytes. The bytes contain the UTF8 encoding
of character data. There is no null character terminating the string.
A "Property" is two Strings (name and type) followed by a vector of
bytes. In contrast to the Strings, the value vector may contain
arbitrary bytes, including values that are not allowed in a UTF-8
encoding. A Property is considered to be a single element. Thus, a
vector of Properties starts with a count of the number of Properties,
not the (three times larger) number of component vectors.
9.3.1 Types
The following type names and meanings are defined by the
protocol.
Type Name bytes in value Interpretation
SGAP:boolean 1 0x00 = false
0x01 = true
other values illegal
SGAP:ternary 1 0x00 = no
0x01 = yes
0x02 = maybe
SGAP:byte 1 arbitrary byte value
SGAP:int 4 32-bit 2's complement
integer in network order
SGAP:unsigned 4 32-bit unsigned integer
in network order
SGAP:string arbitrary UTF-8 encoded
SGAP:javastring 2+arbitrary UTF-8 encoded with 16-bit
prefix count
SGAP:cstring arbitrary ASCII with null terminator
SGAP:xml-1.0 arbitrary expression in XML 1.0 syntax
Other type names MAY be defined. Such type names SHOULD take the form
of an internet domain name [RFC-1034] identifying the naming entity,
followed by a colon ":", then the type name assigned by the naming
entity. Thus "lotus.com:DominoInteger", "ietf.org:IANARegistryEntry",
and "cl.cam.ac.uk:2@3" are all acceptable type names.
9.4 Messages
For each message, we present information in the following form (using
the Split Viewers message as an example):
9.4.5 Split Viewers
Opcode: 0x05
ContextName: String
ItemName: String
ViewerNames: vector of String
Indicates to the server that the named viewers are not to be
given the default viewer cell for the named item in the named
context. The default-flag byte must be cleared (value of
0x00).
The numbered section heading gives the name of the message (Split
Viewers, in this case).
The next line gives the value for the opcode byte, in
hexadecimal. Accordingly, a message with the opcode 5 is a Split
Viewers message.
The next lines give the encoding of the message's body. The body of a
Split Viewers consists of three elements in an implicit sequence: a
String, another String, and a vector of Strings. The names of the
elements serve as a clue to their function, and provide a way for the
explanatory text to refer to these elements. The names of elements
(such as "ContextName") are for explanation only and are not
explicitly represented in protocol messages.
The final paragraph summarizes the function of the message and the
meaning of its elements, including any constraints on the values in
the body or in the header.
9.4.1 Declare
Opcode: 0x01
ContextName: String
Name: String
MultiNames: vector of NameDeclaration
where NameDeclaration is
DeclaredName: String
NameModifiers: vector of integer
Declares to the server that the client will use Name as its name. The
client can affect the item with that name and act as the viewer with
that name.
Name and MultiNames are mutually exclusive: if Name is a
non-zero-length String, MultiNames MUST be a zero-length vector. If
Name is a zero-length String, MultiNames MUST NOT be a zero-length
vector.
For each NameDeclaration in MultiNames, the DeclaredName MUST NOT be a
zero-length String. Implementations MUST reject requests in which the
same DeclaredName appears more than once.
Elements of NameModifiers can be any of the following:
0x1 "ItemOnly" the client may affect the named item but will not
act as the named viewer.
0x2 "ViewerOnly" the client may act as the named viewer but will
not affect the named item.
0x3 "Exclusive" the client insists that it is the only declarer
of this name in this form
An implementation MUST reject any request that includes both
"ItemOnly" and "ViewerOnly" in NameModifiers.
"Exclusive" alone means that no other client may affect the item by
that name or act as the viewer by that name. The item is
still potentially available to other viewers.
"Exclusive" and "ItemOnly" together mean that no other client may
affect the item by that name, although other clients may declare the
same name "ViewerOnly".
"Exclusive" and "ViewerOnly" together mean that no other client may
act as the viewer with that name, although other clients may declare
the same name "ItemOnly".
9.4.2 Create
Opcode: 0x02
ContextName: String
ItemName: String
ViewerNames: vector of String
NewProperties: vector of name-value pairs
Creates new properties contained within the named item in the named
context. Affects the cells determined by the combination of the
default-flag byte and ViewerNames.
A single create request takes place atomically. No client sees the
result of a partially executed create.
An implementation MUST reject the creation of a property that already
exists in any of the cells affected.
Causes create notifications to be delivered to viewers that have
enabled notifications.
9.4.3 Modify
Opcode: 0x03
ContextName: String
ItemName: String
ViewerNames: vector of String
NewProperties: vector of name-value pairs
Replaces the properties contained within the named item in the named
context. Affects the cells determined by the combination of the
default-flag byte and ViewerNames.
A single modify request takes place atomically. No client sees the
result of a partially executed modify.
An implementation MUST reject the modification of a property that does
not exist in any of the cells affected.
Causes modify notifications to be delivered to viewers that have
enabled notifications.
9.4.4 Delete
Opcode: 0x04
ContextName: String
ItemName: String
ViewerNames: vector of String
NewProperties: vector of name-value pairs
Deletes the properties contained within the named item in the named
context. Affects the cells determined by the combination of the
default-flag byte and ViewerNames.
A single delete request takes place atomically. No client sees the
result of a partially executed delete.
An implementation MUST reject the deletion of a property that does not
exist in any of the cells affected.
Causes delete notifications to be delivered to viewers that have
enabled notifications.
9.4.5 Split Viewers
Opcode: 0x05
ContextName: String
ItemName: String
ViewerNames: vector of String
Indicates to the server that the named viewers are not to be given the
default viewer cell for the named item in the named context. The
default-flag byte must be cleared (value of 0x00).
9.4.6 Merge Viewers
Opcode: 0x06
ContextName: String
ItemName: String
ViewerNames: vector of String
Indicates to the server that the named viewers are to be given the
default viewer cell for the named item in the named context. The
default-flag byte must be cleared (value of 0x00).
9.4.7 List Viewers
Opcode: 0x07
ContextName: String
ItemName: String
Requests a list of the names of named viewers (those viewers with
other than the default view of the named item). The default-flag byte
must be cleared (value of 0x00).
The server MUST reject this request if sent by any client that has not
succesfully declared itself as the named item.
9.4.8 Viewer List
Opcode: 0x08
ContextName: String
ItemName: String
Viewers: vector of String
The Viewer list is the list of explicitly named viewers for the object
named. All other viewers receive the default properties for that
object. Note that the server does not know or care whether there are
any actual differences between the properties in the default view cell
and the properties in other view cells. The default-flag byte must be
cleared (value of 0x00).
9.4.9 Fetch
Opcode: 0x09
ContextName: String
ViewerName: String
ItemNames: vector of String
AndEnable: vector of bytes
Requests the properties of the named items, on behalf of the named
viewer. The default-flag byte must be cleared (value of 0x00). Each
name in ItemNames MUST be distinct.
A single fetch request takes place atomically. No client sees the
result of a partially executed fetch.
If AndEnable is not a zero-length vector, then it MUST have the same
number of elements as ItemNames. Each byte MUST be either the value
0x00 (ignore) or 0x01 (enable). For each byte that has the value
"enable", the request enables change notifications immediately for the
item named in the corresponding position of ItemNames (see "Enable",
below).
9.4.10 Fetch Response
Opcode: 0x0A
ContextName: String
ViewerName: String
ObjectInfo: vector of ItemState
where ItemState is
ItemName: String
ItemProperties: vector of name-value pairs
Provides the properties of the named items, in response to a Fetch
request. The default-flag byte must be cleared (value of 0x00).
9.4.11 Enable
Opcode: 0x0B
ContextName: String
ViewerName: String
ItemName: vector of String
Enables the delivery of change notifications. After this command is
received, the server will deliver notifications to the named viewer
whenever any of the named items in the named context change in a way
that is visible to the viewer. The default-flag byte must be cleared
(value of 0x00).
Depending on special server behavior (see Section 8) the server may
deliver these notifications by a different channel rather than an
existing SGAP transport connection. For example, the server may use a
connectionless protocol such as UDP, or may open a server-to-client
TCP connection to deliver the notification.
[[ TBD: specify time limits and renewals. Also arrange for them to be
forwarded by outgoing proxy. ]]
9.4.12 Disable
Opcode: 0x0C
ContextName: String
ViewerName: String
ItemNames: vector of String
Disables the delivery of notifications of changes. After this command
is received, the server will not deliver any notifications to the
named viewer from changes to the named items. The default-flag byte
must be cleared (value of 0x00).
After issuing a disable request, a client must be prepared to receive
some number of spurious (late) notifications and silently discard them.
9.4.13 Creation
Opcode: 0x0D
ContextName: String
ViewerNames: vector of String
ItemName: String
ItemProperties: vector of name-value pairs
Provides a notification to the named viewers that the named properties
have been created as part of the named item (using a Create command).
The default-flag byte must be cleared (value of 0x00).
The ViewerNames are the viewers declared by this client that are
receiving this notification, not all viewers receiving the
notification. In particular, note that ViewerNames in this message is
not identical to ViewerNames in the Create request that gives rise to
this message.
Note also that not all of a client's viewers with access to the item
will be named in ViewerNames: some of them may have not enabled
notifications.
9.4.14 Modification
Opcode: 0x0E
ContextName: String
ViewerNames: vector of String
ItemName: String
ItemProperties: vector of name-value pairs
Provides a notification to the named viewers that the named properties
of the named item have been modified (using a Modify command).
The default-flag byte must be cleared (value of 0x00).
The ViewerNames are the viewers declared by this client that are
receiving this notification, not all viewers receiving the
notification. In particular, note that ViewerNames in this message is
not identical to ViewerNames in the Modify request that gives rise to
this message.
Note also that not all of a client's viewers with access to the item
will be named in ViewerNames: some of them may have not enabled
notifications.
9.4.15 Deletion
Opcode: 0x0F
ContextName: String
ViewerNames: vector of String
ItemName: String
ItemProperties: vector of String
Provides a notification to the named viewers that certain properties
of the named item have been deleted (using a Delete command).
The default-flag byte must be cleared (value of 0x00).
The ViewerNames are the viewers declared by this client that are
receiving this notification, not all viewers receiving the
notification. In particular, note that ViewerNames in this message is
not identical to ViewerNames in the Modify request that gives rise to
this message.
Not all of a client's viewers with access to the item will be named in
ViewerNames: some of them may have not enabled notifications.
9.4.16 OK
Opcode: 0x10
This is sent as an acknowledgement that a previous request was
successfully completed, without errors. All requests except List
Viewers and Fetch cause the server to reply OK if the request
completed successfully.
9.4.17 Error
Opcode: 0xFF
ContextName: String
Code: Cardinal
StringData: String
Explanation: String
Provides a machine-processable error code, some data providing further
context for the error, and a simple explanation that can be used for
debugging. The explanations provided here are typical examples,
rather than mandatory. Any such explanation provided by the server
MUST NOT be presented to a user except as debugging information.
Instead, the error code should be used to map to an appropriately
localized error message.
Error code StringData interpretation Explanation
1 Opcode value received, "Unrecognized Opcode"
as UTF-8 decimal representation
2 None "Not Authenticated"
3 Depends on authentication "Authentication Failed"
protocol
5 Item name "Not Authenticated to
Affect Item"
6 Viewer name "Not Authenticated to
Act As Viewer"
7 Viewer name "No Such Viewer"
8 Maximum bytes allowed in "Value Exceeded
Server's
value, as UTF8 representation Maximum Length"
10. Acknowledgements
SGAP is a descendant of NSTP [NSTP, DPM] and has benefited from John
Patterson's perspective in the design of that protocol. In addition,
comments and criticism by Rob Ullmann, Dave Mitchell, and Sandeep
Singhal have contributed greatly to improving the design.
11. References
[DPM] Mark Day, John F. Patterson, and David Mitchell. "The
Notification Service Transfer Protocol (NSTP): Infrastructure for
Synchronous Groupware." Computer Networks and ISDN Systems, 1997.
[NSTP] Mark Day, John Patterson, Jakov Kucan, David Mitchell, Wei-Meng
Chee. The Notification Service Transfer Protocol. Lotus Workgroup
Technologies Technical Report 96-08, 1996.
[RFC-1034] Paul Mockapetris. "Domain Names -- Concepts and
Facilities." RFC-1034, November 1987.