INTERNET-DRAFT Mark Day Expires: July 14, 1998 Lotus Development Corporation Matrix Model for Selective Dissemination draft-day-msd-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 year-2000 problem (Y2K problem) is of increasing interest. Little has been said about the relationship of Y2K to synchronous groupware. We describe a matrix model of selective dissemination of information to viewers of that information. The model is suitable for some forms of synchronous groupware. 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.