Elvin.Org D. Arnold, Editor Preliminary INTERNET-DRAFT Mantara, Inc Expires: 13 Feb 2008 13 Aug 2007 Elvin Client Protocol 4.0 draft-elvin-client-40-07.txt 1. Status of this Memo This document is an Internet-Draft and is NOT offered in accordance with Section 10 of RFC2026, and the author does not provide the IETF with any rights other than to publish as 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 mate- rial or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/1id-abstracts.html The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html 2. ABSTRACT This document describes a client access protocol for the Elvin noti- fication service. It includes a general overview of the system architecture, and defines an access protocol in terms of operational semantics, an abstract protocol, and a default concrete implementa- tion of the abstract protocol. 3. INTRODUCTION Elvin is a content-based publish/subscribe notification service. An Elvin implementation is comprised of Elvin routers that forward and deliver messages, called notifications, after evaluating their con- tents against a body of registered subscriptions. Elvin notifications are collections of named, typed values. Sub- scriptions are logical predicate expressions that the router evalu- ates for each received notification. Notifications are delivered to the subscriber if the result of the predicate evaluation is true. Elvin clients can be characterised as producers or publishers, which send notifications; and consumers or subscribers, which request Arnold, ed. Expires in 6 months [Page 1] Internet Draft Elvin Client Protocol 4.0 August 2007 delivery of notifications from the service. Consumers normally sub- scribe to receive notifications matching some supplied criteria. While directed communication is well serviced by the Internet proto- col suite, undirected communications, where the sender is unaware of the identity, location or even existence of the receiver, is limited to the various forms of multicast. While multicast is appropriate for many applications, it is inherently channel-based: a particular address and port must be shared by the communicating applications. Elvin is a notification service that provides fast, simple, undi- rected messaging, using content-based selection of delivered notifi- cations. It has been show to work on a wide-area scale and is designed to complement the existing Internet protocols. Elvin notifications are routed from their source to required destina- tions by Elvin router(s). Delivery has best-effort, at-most-once semantics. Under no circumstances should an Elvin client receive duplicate notifications. Notifications from a single source must be delivered in order, but interleaving of notifications from different sources is allowed in any order. The inter-router protocol is not specified by this document. It is noted, however, that notifications are forwarded between routers, and that such journeys are subject to filtering and greater latency than notifications between clients of a single router process. 4. TERMINOLOGY This document discusses clients, client libraries, routers, produc- ers, consumers, quenchers, notifications and subscriptions. An Elvin router is a daemon process that runs on a single machine. It acts as a distribution mechanism for Elvin notifications. An Elvin client is a program that uses the Elvin router, via a client library for a particular programming language. A client library implements the Elvin protocol and manages clients' connections to an Elvin router. Clients can have three roles: producer, consumer or quencher. Pro- ducer clients create notifications: a form of structured message, and send them, using a client library, to an Elvin router. Consumer clients establish a session with an Elvin router and register a request for delivery of notifications matching a subscription expres- sion. Quenching clients also establish a session with an Elvin router, and register a request to be informed of changes to the router's subscription database that match criteria supplied by the quencher. Clients MAY take any number of the producer, consumer and quencher roles concurrently. Arnold, ed. Expires in 6 months [Page 2] Internet Draft Elvin Client Protocol 4.0 August 2007 4.1. Notation Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. 5. ARCHITECTURE This document describes a protocol used by lightweight clients to access the Elvin service provided by an Elvin router. Typically, such clients are implemented as a library module for a particular programming language. An Elvin router implementation can support many concurrent clients. Additional protocols, not specified in this document, enable federa- tion [ERFP] of routers to form a message routing network, and config- uration of redundant routers [EFOP]. The client protocol is defined as an abstract specification, which may be made available in any number of concrete specifications using appropriate underlying facilities. The client protocol is broken into several subsets. An implementa- tion may choose which subsets to provide, depending upon the needs of its intended application programs and the resources available from its host platform. 5.1. Abstract Communications Channel Elvin clients communicate with an Elvin router using a communications channel. A client process MAY open multiple simultaneous channels to a one or more Elvin routers (including multiple channels to the same router). Each such channel is a distinct logical entity. Concrete implementations of this abstract channel MUST provide ordered, reliable, bi-directional delivery of messages of known size; there is no requirement for streaming data. Once created, a channel remains available for exchange of messages until it is closed by either the Elvin client or router. 5.1.1. Offers Elvin router offers are stable, advertised entities to which clients can connect, creating a channel. Offers are described using a Uniform Resource Identifier (URI). The format of this URI is completely defined in [EURI]. An offer's URI specifies the concrete channel implementation offered, and appropri- ate addressing and any other information required to establish a channel. Arnold, ed. Expires in 6 months [Page 3] Internet Draft Elvin Client Protocol 4.0 August 2007 5.1.2. Messages An abstract Elvin message consists of an ordered sequence of values. Each value has a known type, being one of a set of basic data types with a minimum required range of possible values, or an ordered sequence of such basic values of known size. Messages are transferred over the abstract channel. They MUST be delivered completely or not at all, and MUST be received in the order they were sent. 5.2. Concrete Communications Channels An implementation of the abstract channel provides a mechanism for transporting messages between Elvin clients and routers. This mecha- nism may be composed of several parts, cooperating to provide the abstract channel semantics and various qualities of service. Each of these components is referred to as a protocol module, and the combi- nation as the protocol stack. More specifically, the minimum functionality required of a concrete channel is conversion of Elvin messages into a form suitable for transfer, and the transfer of that message form to its destination, where the orginal message must be reconstructed. This document describes two such concrete protocol modules: a means of data transfer using TCP streams, and a means of message encoding and decoding using XDR. Protocol modules are named with a sequence of ASCII characters. These names must uniquely identify the mecha- nism implemented by the protocol module. A concrete endpoint is advertised using a URI. An example of such a URL might be, elvin:/tcp,krb5,xdr/router.example.com:2917 specifying an endpoint using concrete protocol modules "tcp", "krb5" and "xdr", and offered at an address of "router.example.com:2917". As this example shows, protocol modules that provide additional func- tionality, such as encryption, authentication, compression, etc, may form part of the concrete channel's protocol stack. A concrete channel MAY limit the size of messages, but MUST otherwise support the full functionality of the abstract channel. 5.3. Protocol Overview Interactions between client applications and the Elvin router can be characterised as either session-oriented or session-less. Session-less operation is very restricted in its capabilitites. It is provided for specialised clients and is not the general mode of operation. Clients usually establish a session with an Elvin router Arnold, ed. Expires in 6 months [Page 4] Internet Draft Elvin Client Protocol 4.0 August 2007 and maintain that session as long as required. This section provides a high level overview of the protocol and its basic operations. The details of each specific packet and its seman- tics is convered later, in the Protocol Details section. 5.3.1. Notification Elvin notifications are structured messages comprised of a set of attributes. Each attribute consists of a name and a typed value. An attribute name is a string value from a subset of the printable ASCII character set. The maximum length of an attribute name is 1024 bytes. An attribute name may have any value comprised of legal char- acters; there are no reserved values. Hard limit of 1024 ASCII chars in names?!? Attribute values may be any of a signed 32 bit integer, signed 64 bit integer, 64 bit IEEE-954 floating point number, Unicode UTF-8 string, or an ordered sequence of arbitrary octets of known length. Notifications are constructed by Elvin clients, and forwarded to an Elvin router for dissemination. 5.3.2. Subscription An Elvin subscription is a UTF-8 string forming an expression in the Elvin Subscription Language. The expression is registered with an Elvin router, which determines whether to deliver notifications to the subscriber by evaluating the expression in the context of the notification's attributes. If the result of this evaluation is a logical true, a copy of the notifica- tion is queued for delivery. 5.3.3. Quenching An Elvin client can also register a set of attribute names with the Elvin router, and is subsequently kept informed of active subscrip- tion expressions that refer to any of the registered names. The router sends a quenching client branches of the compiled syntax tree created when it compiles the subscriptions during their regis- tration. Quenching clients can use this information for any purpose; the facility was named after its use enabling a producer client to emit only those notifications for which it has been informed a Arnold, ed. Expires in 6 months [Page 5] Internet Draft Elvin Client Protocol 4.0 August 2007 subscription exists, thus quenching the flow of published informa- tion. 5.4. Protocol Interactions 5.4.1. Session-less Notification Client libraries MAY implement session-less transfer of messages from the client to the router. It is not possible for clients to receive notifications outside of a session. +-------------+ +---------+ | Producer | ----UNotify----> | Router | NOTIFICATION +-------------+ +---------+ No other packets are allowed during session-less operation. 5.4.2. Establishing a Session A Elvin client-router session is a bi-directional communciations link. It is used by the client to request deliveries from the router. The router uses the same link to acknowledge client changes and to asynchronously deliver the messages selected by the client. When a client requests a connection, the router will respond with either a Connection Reply, a Disconnect or a Negative Acknowledge- ment. If the router accepts the request, it will respond with a Connection Reply, containing the agreed parameters of the connection. +-------------+ ---ConnRqst--> +---------+ | Client | | Router | SUCCESSFUL CONNECTION +-------------+ <---ConnRply-- +---------+ 5.4.3. Sending Notifications After a successful connection exchange, the session is active and a client may start emitting notifications by sending them to the router for distribution. If the attributes in the notification match any subscriptions held at the router for consumers, the consumers match- ing those subscriptions SHALL be be sent a notification deliver mes- sage with the content of the original notification. The NotifyDeliver packet differs slightly from the original Noti- fyEmit sent by the producer. As well as the sequence of named-typed- values, it contains information about which subsciptions were used to match the event. This allows the client library of the consumer to dispatch the event with out having to do any additional filtering. Arnold, ed. Expires in 6 months [Page 6] Internet Draft Elvin Client Protocol 4.0 August 2007 +----------+ +--------+ | Producer | ---NotifyEmit---> | | +----------+ | | | Router | NOTIFICATION PATH +----------+ | | | Consumer | <--NotifyDeliver- | | +----------+ +--------+ 5.4.4. Setting Subscriptions When a session is first established, the router MUST NOT send any Notify Deliver packets until at least one subscription has been added by the client. A Consumer client describes the events it is interested in by sending a predicate expression in the Elvin subscripton language (and its associated security keys) to the Elvin router. The predicate is sent in a Subscription Add Request (SubAddRqst). On receipt of the request, the router checks the syntactic correctness of the predi- cate. If valid, a Subscription Reply (SubRply) is returned which includes a router-allocated indentifier for the subscription. +----------+ --SubAddRqst--> +--------+ | Consumer | | Router | ADDING A SUBSCRIPTION +----------+ <---SubRply---- +--------+ If the predicate fails to parse, the router MUST send a Negative Acknowledgement (Nack) to the client with the error code set to indi- cate a parser error. This is effectively an RPC-style interaction. All operations that modify a client's session information at the router use this RPC style. A client may alter its registered predicate using the Subscription Modify Request or remove it entirely by sending a Subscription Delete Request. Such requests use the subscription identifier returned from the SubAddRqst. The router MAY allocate a new subscription identi- fier when a subscription is changed. An attempt to modify or delete a subscription identifier that is not registered is a protocol error, and the router MUST send a Nack to the client (see Protocol Errors). Quenching is a facility named for its ability to reduce notification traffic by preventing the propagation of unwanted notifications. It enables clients to use therouter's knowledge of consumers subscrip- tions to prevent producers from notifying events for which no sub- scription exists. Once connected, the client MAY request that it be notified when there are changes in the subscription database managed by the router. The client can request such information on subscriptions referring to named attributes. Requesting notification of changes to subscriptions referring to a set of named attributes uses the Quench Add Request (QnchAddRqst) message. The Quench Reply (QnchRply) message returns an identifier Arnold, ed. Expires in 6 months [Page 7] Internet Draft Elvin Client Protocol 4.0 August 2007 for the registered request. +----------+ --QnchAddRqst--> +--------+ | Quencher | | Router | ADDING A QUENCH +----------+ <---QnchRply---- +--------+ As for subscriptions a quench MAY be modified and/or removed later by a client using the quench-id. Modifying a quench request MAY change the identifier used by the router to refer to the request. Subscriptions containing the requested quenching terms are sent to the client as an abstract syntax tree. Three types of changes are possible: a new subscription referring to the registered attribute names is registered, a subscription is modified to either refer to or no longer refer to the specified attributes, or a matching subscrip- tion is removed. +----------+ ----SubAddRqst---> +--------+ | Consumer | | | +----------+ <----SubRply------ | | | Router | +----------+ | | | Quencher | <--SubAddNotify--- | | +----------+ +--------+ SUBSCRIPTION ADD NOTIFICATION 5.4.5. Renegotiating Connection Options A client can request alterations to the session's properties at any time during the life of the session. When a client requests the the connection options be renegotiated, the router will respond with either a QoS Reply or Negative Acknowl- edgement. +-------------+ ---QosRqst---> +---------+ | Client | | Router | OPTION RENEGOTIATION +-------------+ <---QosRply--- +---------+ 5.4.6. Lost Packets The router may choose to drop notification packets (NotifyEmit, Sub- AddNotify, SubModNotify, SubDelNotify) packets if a client is not reading them quickly enough. If this happens, the router is obliged to send a DropWarn packet to the client, indicating that one or more notification packets were dropped. +----------+ +--------+ | Consumer | <---DropWarn--- | Router | DROPPED PACKET WARNING +----------+ +--------+ Arnold, ed. Expires in 6 months [Page 8] Internet Draft Elvin Client Protocol 4.0 August 2007 5.4.7. Ending a Session At any time after a receiving a Connection Reply, the router can inform the client that it is to be disconnected. The Disconn packet includes an explanation for the disconnection, and optionally, directs the client to reconnect to an alternative router. +-------------+ +---------+ | Client | <----Disconn---- | Router | DISCONNECTION +-------------+ +---------+ To disconnect from the router, the client sends a Disconnect Request. It SHOULD then wait for the router's response Disconnect Reply, which ensures that both directions of the communication channel have been flushed. The router MUST NOT refuse to disconnect a client (ie. using a Nack). +-------------+ ---DisconnRqst--> +---------+ | Client | | Router | DISCONNECTION +-------------+ <--DisconnRply--- +---------+ 6. SUBSCRIPTION LANGUAGE Consumer clients register subscription expressions with a router to request delivery of messages. The language used for these expres- sions is defined in this section. The subscription language syntax and semantics are considered part of the protocol: all routers sup- porting a particular protocol version will understand the same sub- scription language. There is no provision for alternative languages. A consumer client registers a subscription expression that the router evaluates on its behalf for each message delivered to the router. If the expression evaluates to true then the notification is delivered, otherwise, it it not delivered. 6.1. Subscription Expressions 6.1.1. Logic The evaluation of a subscription uses Lukasiewicz's tri-state logic that adds the value bottom (which represents "undecideable" or "indefinite") to the familiar true and false. Arnold, ed. Expires in 6 months [Page 9] Internet Draft Elvin Client Protocol 4.0 August 2007 --------------------------------------------------------- Lukasiewicz tri-state logic table --------------------------------------------------------- A B | ! A A && B A || B A ^^ B ----------------+---------------------------------------- true true | false true true false true bottom | false bottom true bottom true false | false false true true bottom true | bottom bottom true bottom bottom bottom | bottom bottom bottom bottom bottom false | bottom false bottom bottom false true | true false true true false bottom | true false bottom bottom false false | true false false false ----------------+---------------------------------------- Any subscription expression that refers to a name that is not present in the notification being evaluated results in bottom. In addition, many of the functions in Elvin have constraints on their parameters (ie. data type) and an undefined result should these con- straints not be met. For example, where a string parameter is expected but the type of the actual parameter is a 32 bit integer, the result of the function begins-with() is bottom. Notifications are delivered only if the result of subscription evalu- ation is true. It should be emphasized that: There is neither an explicit boolean type nor are there boolean constants for true or false. Whereas some programming languages, such as C and C++, pro- vide an implicit conversion from numeric values to truth values (zero means false, nonzero means true), the Elvin subscription language requires such a conversion to be made explicit, for example (Example != 0) 6.1.2. Grouping Clauses in an expression may be grouped using parentheses to override precedence of evaluation. Unlike the logical or arithmetic opera- tors, parentheses need not be separated from attribute identifiers or literal values by whitespace. An implementation MAY limit the depth of nesting able to be evaluated in subscription expressions; an expression that exceeds this limit MUST generate a NESTING_TOO_DEEP error in response to registration with the router. Arnold, ed. Expires in 6 months [Page 10] Internet Draft Elvin Client Protocol 4.0 August 2007 6.1.3. Logical Operators A subscription expression may be a single predicate, or it may con- sist of multiple predicates composed by logical operators. The logi- cal operators are && Logical AND || Logical OR ^^ Logical Exclusive-OR ! Logical NOT (unary) Logical NOT has highest precedence, followed by AND, XOR and then OR. 6.1.4. Literal Syntax A subscription expression may include literal values for most of the message data types. These types are Integer Numbers int32 A 32 bit, signed, 2's complement integer. int64 A 64 bit, signed, 2's complement integer. Integer literals can be expressed in decimal (the default), hexadeci- mal, using a 0x prefix, or octal, using a 0 prefix. In all cases, an optional leading minus sign negates the value, and a trailing "l" or "L" indicates that the value should be of type int64. Literal values too large to be converted to an int32, but without the suffix specifying an int64 type MUST cause an OVERFLOW error. Simi- larly, values with the suffix and too large to be converted to an int64, MUST cause an OVERFLOW error. Real Numbers real64 An IEEE 754 double precision floating point number. Real literals can be expressed only in decimal, and must include a decimal point and both whole and fractional parts. An optional inte- ger exponent may be added following an "e" or "E" after the frac- tional part. A real literal with an exponent too large for the IEEE 754 double precision format MUST cause an OVERFLOW error. Superfluous precision in the mantissa SHOULD be discarded. Arnold, ed. Expires in 6 months [Page 11] Internet Draft Elvin Client Protocol 4.0 August 2007 Character Strings string A UTF-8 encoded Unicode string of known length, with no NUL (0x00) bytes. String literals must be quoted using either double (Unicode QUOTATION MARK U+0022) or single (Unicode APOSTROPHE U+0027) quote characters. Within the (un-escaped) quotes, a backslash (Unicode REVERSE SOLIDUS U+005C) character functions as an escape for the following character. All escaped characters except the quotes represent themselves. There is no mechanism for including special characters in string lit- erals; each language mapping is expected to use its own mechanism to achieve this. Opaque Octet Data opaque An opaque octet string of known length. The subscription language does not support opaque literals; reference to opaque attributes in a subscription expression is limited to use of the size() function. There are no structured data types (C struct, enum or union), nor is there a boolean data type. All of these can be implemented simply using the existing types and structured naming. String and opaque data values have known sizes (ie. they don't use a termination character). An implementation MAY enforce limits on these sizes; see section X on Router Features. 6.1.5. Reference Syntax Predicates and function may also use values obtained from the message under evaluation. Values are referred to using the name of the mes- sage attribute. Names must be separated from operators by whitespace. What other rules here? 6.1.6. General predicates The subscription language defines a number of predicates that return boolean values. Any predicate may be applied to any attribute name. If the named attribute does not exist in the current notification, or exists but has an inappropriate type for the predicate, the predicate returns bottom. require(attribute) Returns true if the notification contains an attribute whose name exactly matches that specified (even if the attribute's value is, Arnold, ed. Expires in 6 months [Page 12] Internet Draft Elvin Client Protocol 4.0 August 2007 say, an empty string or a zero-length opaque value). int32(attribute) Returns true if the type of the attribute is int32. int64(attribute) Returns true if the type of the attribute is int64. real64(attribute) Returns true if the type of the attribute is real64. nan(attribute) Returns true if the type of the specified attribute is real64 and its value is the IEEE 754-defined constant NaN (not a number). There is no literal constant value for NaN because comparing the value of an attribute against such a numeric expression is equiv- alent to using this predicate. string(attribute) Returns true if the type of the attribute is string. opaque(attribute) Returns true if the type of the attribute is opaque. 6.1.7. Equality and Set Membership The most common operation in typical subscription expressions is a test for equality. equals(attribute, attribute-or-literal+) Returns true if the type and value of the first parameter match those of any of the subsequent parameters. For convenience, two operators are defined using this basic predi- cate. == Equal to. Compares its two operands, each of which may be a literal value or an attribute name. Comparing two attribute names is allowed, but com- paring two literal values is pointless and SHOULD return an error. Mantara's implementation currently rejects any pair of operands without at least one attribute name,but the returned error is not defined in this specification. != Not equal to. This operator is defined to be implemented as Arnold, ed. Expires in 6 months [Page 13] Internet Draft Elvin Client Protocol 4.0 August 2007 !(A == B) Note that this can lead to unexpected results when the attributes are not defined. 6.1.8. String predicates Some of the most used features of the subscription language are its string predicates. The most general provides regular-expression ("regex") matching, but simpler predicates are also provided, ranging from wildcarding (or "globbing") to simple string comparision. While these could all be replaced by regular-expression operations, it is generally clearer to use and more efficient to implement the simpler forms when they suit. The string predicates are: contains(attr, stringconst+) Returns true if any stringconst is a substring of the value of attr. begins-with(attr, stringconst+) Returns true if any stringconst is an initial substring (prefix) of the value of attr. ends-with(attr, stringconst+) Returns true if any stringconst is a final substring (suffix) of the value of attr. wildcard(attr, stringconst+) Returns true if the value of attr matches a wildcard ("glob") expression specified by any stringconst value. Need pointer to glob semantics. regex(attr, stringconst) Returns true if the value of attr matches the regular expression specified by the stringconst. Need pointer to (E?)RE semantics. In the definitions above, the empty (zero-length) substring is defined to be a substring of every string, and any string is a sub- string of itself. Thus begins-with and ends-with imply contains, and equals (the general predicate) implies all three of them. There are no predicates for string comparison, i.e. testing whether one string "is less than" another string. 6.1.9. Size Function size(attribute) Where attribute is the name of a string or opaque value, this function returns its size in bytes. For all other value types, the enclosing expression is set to bottom. Arnold, ed. Expires in 6 months [Page 14] Internet Draft Elvin Client Protocol 4.0 August 2007 Note that the size in bytes of a UTF-8 string value does not nec- essarily reflect the number of characters. 6.1.10. Implications of International Characters Unicode characters introduce some complexity to the string predi- cates. Comparison of Unicode characters must consider two aspects: character decomposition, and strength of the comparison. 6.1.10.1. Decomposition A single Unicode "character" might consist of a base character together with a number of combining characters (such as accents), represented as either a single, pre-composed character, or as a sequence of characters which are combined for presentation. In addi- tion, because the Unicode standard attempts to encompass existing character sets, there can be multiple representations of the same basic character. In order to compare two Unicode strings, you might want to ensure that two different representations of the same character compare as equal. In order to do this, pre-composed characters (consisting of a base character and some combining characters), can be decomposed to a canonical representation. For example, LATIN SMALL LETTER A WITH GRAVE (U+00E0) decomposes to the two characters LATIN SMALL LETTER A + COMBINING GRAVE ACCENT (U+0061 + U+0300) As an additional complication, there exist Unicode characters that have multiple pre-composed representations, and in performing decom- position, the information about which original character was used is lost. The process of performing decomposition of these characters (in addition to those for which the process is straight-forward) is called compatibility decomposition. Two string functions are provided to perform decomposition of Unicode strings prior to comparison: decompose(string) Perform canonical decomposition of the supplied string and return the resulting string value. decompose-compat(string) Perform compatible (and canonical) decomposition of the supplied string and return the resulting string value. Arnold, ed. Expires in 6 months [Page 15] Internet Draft Elvin Client Protocol 4.0 August 2007 6.1.10.2. Comparison Strength Unicode defines four levels of comparison, in which equivalence of any two strings depends on the comparison level and the locale, as well as the strings themselves [UNICODE]. Because the locale of a notification is not available to an Elvin router, locale-dependent comparisons are not appropriate. Unicode also defines a mapping from each character to a form of that same character in a canonical case, known as folded case, which is typically the same as lower case for characters with case (note that most characters have only one case form). Folded case is largely independent of locale, with only a very small number of exceptions. The string function "fold-case(string)" is provided to transform strings to folded case and allow case-insensitive string comparison. 6.1.11. Numeric predicates The numeric predicates are the usual arithmetic comparison operators: == Equal to < Less than <= Less than or equal to > Greater than >= Greater than or equal to These predicates can be applied to numeric literals, attributes and expressions. When applied to attributes, or expressions containing an attribute, it is important to understand the effect of using an undefined attribute name. A reference to an undefined attribute sets the closest enclosing boolean expression to false. false? or bottom? This will normally mean that the numeric predicate will return false, leading to apparently anomalous cases: Arnold, ed. Expires in 6 months [Page 16] Internet Draft Elvin Client Protocol 4.0 August 2007 Consider an expression referring to two int32 attributes A <= B || A > B While it could be expected that this expression would always return true, in fact it will return false if neither A nor B is defined. The application of the equality predicate to values of type real64 can also appear anomalous due to rounding errors. Two real64 values are defined to be equal if their sign, mantissa and exponent are all equal. More useful comparison of real64 numbers can be achieved using the less-than and greater-than predicates. 6.1.12. Numeric functions The following functions are defined on all three numeric types: + Addition - Subtraction (also unary negation) * Multiplication / Division The following operators are defined only on the two integer types, int32 and int64: Need to pin down 5- and 6-bit shifts (and different promotion rules?),as Java does. Also modulus could be done for real64 too (Java does),but why? % Remainder (modulus) << Left shift >> Right shift, signed/arithmetic (shift in the value of the sign bit) >>> Right shift, unsigned/logical (shift in 0) & Bitwise AND | Bitwise OR ^ Bitwise XOR ~ Bitwise inversion (unary) Arnold, ed. Expires in 6 months [Page 17] Internet Draft Elvin Client Protocol 4.0 August 2007 6.2. Numeric type promotion The three numeric types (int32, int64 and real64) may be mixed freely in numeric expressions, and Elvin performs automatic type promotions when necessary. If the arguments to a numeric predicate or the components of an expression have different numeric types, their values are promoted to a common numeric type before the predicate or expression is evalu- ated. For an expression, the type of the result value is always the promoted type, even if the result would fit in a smaller type. The promotion rule is "real64 > int64 > int32", or in other words: 1. If either operand is real64, the promoted type is also real64. 2. Otherwise, if either operand is int64, the promoted type is also int64. 3. Otherwise, both operands must be int32, and no promotion is required. 6.3. Subscription Errors Elvin subscriptions are compiled by the router during registration. Various errors are possible; this section documents the basic error conditions. Errors detected when adding or modifying a subscription are reported as protocol errors. The router returns a failure code, some addi- tional parameters, and a default text message. Clients can use the error code to generate localized text including the parameter values, if desirable. Router implementations MAY return error codes not specified here, but SHOULD use the standard codes where appropriate. This section refers to names from the error table in section "Nega- tive Acknowledgement", which defines the error codes, parameters and required client action. PARSE_ERROR A non-specific problem occured when parsing the expression. INVALID_TOKEN An invalid token was parsed in the expression. UNTERM_STRING A string literal in the expression is missing a terminating quote character. Arnold, ed. Expires in 6 months [Page 18] Internet Draft Elvin Client Protocol 4.0 August 2007 OVERFLOW A numeric literal value in the expression is too large for its type. TYPE_MISMATCH The type of a literal value in the expression does not match its usage. UNKNOWN_FUNC An unrecognised predicate function is used in the expression. TOO_FEW_ARGS A predicate function is called with too few arguments. TOO_MANY_ARGS A predicate function is called with too many arguments. EXP_IS_TRIVIAL When compiled, the expression reduced to a constant value. INVALID_REGEXP A regular expression was invalid. REGEXP_TOO_COMPLEX A regular expression was too complex. Note also that a router implementation MAY reject a subscription expression that exceeds its internal limits on the length of attribute identifiers and strings. Such errors SHOULD be reported using the QOS_LIMIT error code. 6.3.1. Runtime evaluation errors in numeric expressions During the evaluation of a numeric predicate (including the evalua- tion of any expressions that are the arguments to the predicate), the following classes of errors may occur: 1. Errors that cause the predicate to return bottom: o Use of an attribute that does not exist in the notification, o Use of an attribute, constant or expression that has an inappropriate type (for example, real64, string or opaque in a function that expects int32 or int64) o Integer division by zero. 2. Integer overflow. This is silently ignored and the result is unde- fined, or do we define it to be wrapped to 32 or 64 bits? 3. Floating-point errors, including underflow, overflow and division by zero, are silently mapped to the appropriate IEEE 754 values. Arnold, ed. Expires in 6 months [Page 19] Internet Draft Elvin Client Protocol 4.0 August 2007 Do we want predicates for 754 values,e.g. isNan()? Need to check whether 754 defines all relationals to return FALSE if either argument is NaN. (What about other magic numbers, e.g. underflow?) Does 754 specify behaviour of != with NaN,and how does that compare to Elvin semantics? 7. ABSTRACT PROTOCOL The Elvin4 protocol is specified at two levels: an abstract descrip- tion, able to be implemented using different marshalling and trans- port protocols, and a concrete specification of one such implementa- tion, mandated as a standard protocol for interoperability between different routers. This section describes the operation of the Elvin4 protocol, without describing any particular protocol implementation. Arnold, ed. Expires in 6 months [Page 20] Internet Draft Elvin Client Protocol 4.0 August 2007 7.1. Packet Types The Elvin abstract protocol specifies a number of packets used in interactions between clients and the router. ------------------------------------------------------------- Packet Type Abbreviation Usage Subset ------------------------------------------------------------- Unreliable Notification UNotify C -> S A Negative Acknowledgement Nack S -> C B Connect Request ConnRqst C -> S B Connect Reply ConnRply S -> C B Disconnect Request DisconnRqst C -> S B Disconnect Reply DisconnRply S -> C B Disconnect Disconn S -> C B Security Request SecRqst C -> S B Security Reply SecRply S -> C B Notification Emit NotifyEmit C -> S B Notification Deliver NotifyDeliver S -> C B Subscription Add Request SubAddRqst C -> S B Subscription Modify Request SubModRqst C -> S B Subscription Delete Request SubDelRqst C -> S B Subscription Reply SubRply S -> C B Dropped Packet Warning DropWarn S -> C B Test Connection TestConn C -> S B Confirm Connection ConfConn S -> C B QoS Request QosRqst C -> S C QoS Reply QosRply S -> C C Quench Add Request QnchAddRqst C -> S C Quench Modify Request QnchModRqst C -> S C Quench Delete Request QnchDelRqst C -> S C Quench Reply QnchRply S -> C C Subscription Add Notify SubAddNotify S -> C C Subscription Change Notify SubModNotify S -> C C Subscription Delete Notify SubDelNotify S -> C C ------------------------------------------------------------- A concrete protocol implementation is free to use the most suitable method for distinguishing packet types. If a packet type number or enumeration is used, it SHOULD reflect the above ordering. 7.2. Protocol Subsets The subsets in the above table reflect capabilities of an implementa- tion. An implementation MUST implement all or none of the packet types in a subset. Subsets A and B are independent. An implementation MAY support either or both of subsets A and B. Subset A is OPTIONAL, subset B is RECOMMENDED, and subset C is OPTIONAL. Subsets C is dependent on subset B. An implementation supporting subset C MUST support subset B. Arnold, ed. Expires in 6 months [Page 21] Internet Draft Elvin Client Protocol 4.0 August 2007 i'd like the ability to have quenching only clients. jb to do that,we'd have to separate the ConnRqst/Rply,SecRqst/Rply,Disconn*,DropWarn and Test/ConfConn packets from Notif/Sub packets. it's possible,and maybe nice? da 7.3. Errors Several types of errors are recognised in the protocol specification. This section describes each type of error, and its required handling. 7.3.1. Communications Errors A communications error occurs when an abstract communcications chan- nel closes at an unexpected point in the protocol sequence. The protocol does not support re-establishment of broken abstract communications channel. When a communications error is detected, a router implementation SHOULD clean up all state associated with the channel (and its client), including negotiated connection options, keys, subscrip- tions, quenches, and queued packets. A client implementation MAY attempt to open a new channel, and create a new connection with its current state. However, such a reconnec- tion might cause notification and quench deliveries to be lost, and therefore client applications MUST be notified if such an attempt is made. 7.3.2. Protocol Violations A protocol violation is defined to occur when a message is received that cannot be unmarshalled, has a type that is not expected at the current point in the proto- col sequence, or, is a reply to an unknown request. In all cases of protocol violation, an implementation MAY immediately terminate the communications channel, without performing a connection closure packet exchange. However, a more robust implementation MAY attempt to ignore such mes- sages and maintain the connection, relying on timeouts to initiate a suitable recovery process in its peer implementation. 7.3.3. Protocol Errors A protocol error occurs when a message is received whose values are inconsistent with the state of the receiving entity or otherwise Arnold, ed. Expires in 6 months [Page 22] Internet Draft Elvin Client Protocol 4.0 August 2007 incorrect, but is not a protocol violation. Examples include attempts to modify or delete a non-existent subscription, or sending a notification whose attributes exceed the negotiated connection lim- its. In general, client implementations SHOULD and router implementations MUST, maintain a connection in the face of protocol errors. A router implementation that detects a protocol error in a NotifyEmit packet SHOULD ignore it, and in any other packet SHOULD respond using the Negative Acknowledge (Nack) packet. A client implementation that detects a protocol error in any packet received from the router MAY ignore it or MAY abort the connection. Repeated protocol errors on a channel MAY cause a router implementa- tion to close the client's connection, giving suspected denial of service attack as a reason (see the Disconnect packet). 7.4. Packet Details This section provides detailed descriptions of each packet and their use in the Elvin protocol. Packets are comprised from a set of simple base types and described in a pseudo-C style as structs made up of these types. The following definitions are used in several packets: typedef uint32 id32; typedef uint64 id64; These types are opaque n-bit identifiers. No semantics are required other than bitwise comparison. In all cases, an all zeros value is reserved. Implementations are free to use any type capable of holding the required number of bits for these values. In particular, the signed- ness of the underlying type does not matter. Arnold, ed. Expires in 6 months [Page 23] Internet Draft Elvin Client Protocol 4.0 August 2007 typedef byte[] opaque; union Value { int32 i32; // 4 byte signed integer int64 i64; // 8 byte signed integer real64 r64; // 8 byte double precision float string str; // length encoded UTF-8 Unicode string; no NUL bytes opaque bytes; // binary data sequence }; struct NameValue { string name; Value value; }; Arrays of NameValue elements are used for notification data and description of router options. The value type defines the range of data that may be exchanged using Elvin messages. Note that there are no unsigned integer types, nor an explicit boolean type. struct Keys { struct KeySetList { id32 scheme; struct KeySet { opaque keys[]; } key_sets[]; } key_set_lists[]; }; Keys and keysets are explained more fully in a later section. Arnold, ed. Expires in 6 months [Page 24] Internet Draft Elvin Client Protocol 4.0 August 2007 struct SubASTNode { SubAST[] children; }; union SubAST { string name; int32 i32; int64 i64; real64 r64; string str; string regular_expression; SubASTNode equals; SubASTNode not_equals; SubASTNode less_than; SubASTNode less_than_equals; SubASTNode greater_than; SubASTNode greater_than_equals; SubASTNode or; SubASTNode xor; SubASTNode and; SubASTNode not; SubASTNode unary_plus; SubASTNode unary_minus; SubASTNode multiply; SubASTNode divide; SubASTNode modulo; SubASTNode add; SubASTNode subtract; SubASTNode shift_left; SubASTNode shift_right; SubASTNode logical_shift_right; SubASTNode bit_and; SubASTNode bit_xor; SubASTNode bit_or; SubASTNode bit_negate; SubASTNode is_int32; SubASTNode is_int64; SubASTNode is_real64; SubASTNode is_string; SubASTNode is_opaque; SubASTNode is_nan; SubASTNode begins_with; SubASTNode contains; SubASTNode ends_with; SubASTNode wildcard; SubASTNode regex; SubASTNode fold_case; Arnold, ed. Expires in 6 months [Page 25] Internet Draft Elvin Client Protocol 4.0 August 2007 SubASTNode decompose; SubASTNode decompose_compat; SubASTNode require; SubASTNode equals; SubASTNode size; }; The subscription AST types are used to describe the compiled form of subscription expressions in the quench notification packets. id32 xid Where a request packet is sent by the client (other than NotifyEmit or UNotify), it MUST include transaction identifier (xid), used to match its reply. The xid is a 32 bit number, allocated by the client. The allocation MUST ensure that no packet is sent with the same identifier as an outstanding request. Also, the value zero is reserved, and MUST NOT be used. 7.4.1. Unreliable Notification Unreliable notifications are sent by a client to a router outside the context of a session (see ConnRqst below). Using the protocol and endpoint information obtained either directly or via router discov- ery, a client creates a channel to the router. Over this channel, one or more UNotify packets MAY be sent to the router. The router MUST NOT send any data to the client over the channel. The router MAY close the channel after receiving a single UNotify packet. UNotify packets with an incompatible version number MUST be silently discarded by the router. struct UNotify { uint8 client_major_version; uint8 client_minor_version; NameValue attributes[]; boolean deliver_insecure; Keys keys; }; 7.4.2. Negative Acknowledgement Within the context of a session, many requests can return a Negative Acknowledgement to indicate that although the router understood the request, there was an error encountered performing the requested operation. Arnold, ed. Expires in 6 months [Page 26] Internet Draft Elvin Client Protocol 4.0 August 2007 struct Nack { id32 xid; uint16 error; string message; Value args[] }; The error field is a decimal value structured into ranges with a gen- eral category that indicates what action should be taken by the client, and a specific error number that identifies the problem. Clients MUST handle error values according to their category, and SHOULD present meaningful information to the application derived from the defined error values. Range | Category -------------+------------------------------------------------------------ 0 | Reserved value. | 1 - 999 | A connection establishment error. | 1000 - 1999 | An error has been detected in a protocol message. | This might imply corruption of the connection or | an implementation error. | 2000 - 2999 | An error has been detected in a request. | 3000 - 65535 | Reserved values. Clients MAY interpret implementation-specific error codes, on the basis of router identity determined during connection negotiation. Unrecognised codes MUST be handled according to their general cate- gory. Receiving a reserved error code SHOULD be handled as a protocol error. Code | Name | Arguments | Description -------+--------------------+------------------+-------------------------- 1 | PROT_INCOMPAT | None | ConnRqst rejected due to | | | protocol incompatibility 2 | AUTHZ_FAIL | None | Authorisation failure 3 | AUTHN_FAIL | None | Authentication failure | | | 4 | | | Reserved -499 | | | 500 | | | Implementation-specific -999 | | | connection establishment | | | error | | | 1001 | PROT_ERROR | None | General error in protocol 1002 | NO_SUCH_SUB | subid, id64 | No such subscription 1003 | NO_SUCH_QUENCH | quench_id, id64 | No such quench 1004 | BAD_KEY_SCHEME | scheme_id, id32 | Bad keys scheme 1005 | BAD_KEY_INDEX | scheme_id, id32 | Bad keyset index Arnold, ed. Expires in 6 months [Page 27] Internet Draft Elvin Client Protocol 4.0 August 2007 | | index, int32 | 1006 | BAD_UTF8 | offset, int32 | Invalid UTF-8 string | | | FIXME (libelvin 2301) | | | 1007 | | | Reserved -1499 | | | 1500 | | | Implementation-specific -1999 | | | connection error | | | 2001 | NO_SUCH_KEY | None | No such key 2002 | KEY_EXISTS | None | Key already exists 2003 | BAD_KEY | None | Invalid key 2004 | NOTHING_TO_DO | None | Request required no | | | action 2005 | QOS_LIMIT | property, string | Request exceeds QoS limit 2006 | IMPL_LIMIT | None | Request exceeds | | | implementation limit 2007 | NOT_IMPL | None | Requested feature is | | | not implemented by router | | | 2008 | | | Reserved -2100 | | | | | | 2101 | PARSE_ERROR | offset, int32 | Parse error at offset | | token, string | 2102 | INVALID_TOKEN | offset, int32 | Invalid token | | token, string | 2103 | UNTERM_STRING | offset, int32 | Unterminated string 2104 | UNKNOWN_FUNC | offset, int32 | Unknown function | | name, string | 2105 | OVERFLOW | offset, int32 | Numeric constant overflow | | token, string | 2106 | TYPE_MISMATCH | offset, int32 | Type mismatch | | expr, string | | | type, string | 2107 | TOO_FEW_ARGS | offset, int32 | Too few arguments | | function, string | 2108 | TOO_MANY_ARGS | offset, int32 | Too many arguments | | function, string | 2109 | INVALID_REGEXP | offset, int32 | Invalid regular expression | | regexp, string | 2110 | EXP_IS_TRIVIAL | | FIXME (libelvin has args) 2111 | REGEXP_TOO_COMPLEX | offset, int32 | FIXME (libelvin doesn't | | regexp, string | have offset) 2112 | NESTING_TOO_DEEP | offset, int32 | Expression nesting too deep | | | 2113 | | | Reserved -2200 | | | 2201 | EMPTY_QUENCH | None | Empty quench 2202 | ATTR_EXISTS | name, string | Quench attribute exists 2203 | NO_SUCH_ATTR | name, string | No such attribute | | | 2110 | | | Reserved -2499 | | | Arnold, ed. Expires in 6 months [Page 28] Internet Draft Elvin Client Protocol 4.0 August 2007 2500 | | | Implementation-specific -2999 | | | request failure The Nack message field is a Unicode string template containing embed- ded tokens of the form %n, where n is an index into the args array. When preparing the error message for presentation to the user, each %n should be replaced by the appropriately formatted value from the args array. The language in which the Nack message is sent by a router MAY be negotiated during connection establishment. Alternatively, clients MAY provide local templates to be used for generating the formatted text for presentation to the application. 7.4.3. Connect Request Using the protocol and endpoint information obtained either directly or via router discovery, a client can establish a channel to a router, via an endpoint. It MAY then send a ConnRqst to establish protocol options to be used for the session, and MUST send either a ConnRqst or UNotify. A router SHOULD close a channel from which it has received neither a ConnRqst or a UNotify within a reasonable time period. The ConnRqst MAY contain requests for various protocol options to be used by the connection. These options are identified using a string name. Some options refer to properties of the router, while others MAY be used by the protocol layers. Legal option names, their semantics, and allowed range of values are defined later in the Connection Options section. A router receiving a ConnRqst MUST send a ConnRply, a Nack or a dis- connect in reply. struct ConnRqst { id32 xid; uint8 client_major_version; uint8 client_minor_version; NameValue options[]; Keys nfn_keys; Keys sub_keys; }; 7.4.4. Connect Reply Sent by the Elvin router to a client, a ConnRply accepts the client's connection request. and specifies the connection option values to be provided by the router. Arnold, ed. Expires in 6 months [Page 29] Internet Draft Elvin Client Protocol 4.0 August 2007 struct ConnRply { id32 xid; NameValue options[]; }; For each legal, understood option included in the ConnRqst, a match- ing response MUST be present in the ConnRply. Where the value returned differs from that requested, the client MUST either use the returned value, or request closure of the session (using a Discon- nRqst). Unrecognised options MUST NOT be returned by the router. Additional option values, not requested by the client, MAY be dic- tated by the router. If an option has the specified default value, it MAY be sent to the client, but where the router implementation uses a non-default value, it MUST be sent to the client. 7.4.5. Disconnect Request Sent by clients to the Elvin router to request closure of the ses- sion. struct DisconnRqst { id32 xid; }; A client MUST send this packet and wait for confirmation via Discon- nRply before closing the channel to the router. The client library MUST NOT send any further messages to the router once this message has been sent. The client library MUST continue to read from the channel until a DisconnRply packet is received. A router receiving a DisconnRqst MUST suspend further evaluation and notification of subscriptions and quenches for this client. A Dis- connRply packet MUST be sent to the client's channel, the channel then flushed before being closed. It is a protocol violation for a client to close its channel without sending a DisconnRqst (see protocol violations below). 7.4.6. Disconnect Reply Sent by the Elvin router to a client. This packet is sent in response to a Disconnect Request, prior to breaking the connection. struct DisconnRply { id32 xid; }; This MUST be the last packet sent by a router in a session. The underlying channel MUST be closed immediately after this packet has been successfully delivered to the client. Arnold, ed. Expires in 6 months [Page 30] Internet Draft Elvin Client Protocol 4.0 August 2007 7.4.7. Disconnect Sent by the Elvin router to a client. This packet is sent in two different circumstances: to direct the client to reconnect to another router, or to inform that client that the router is shutting down. struct Disconn { id32 reason; string args; }; where the defined values for "reason" are Reason | Definition --------+-------------------------------------------------------- 0 | Reserved. 1 | Router is closing down. 2 | Router is closing this connection, and directs the | client to connect to the router address in "args". 4 | Router is closing this connection for repeated | protocol errors. This MUST be the last packet sent by a router in a session. The underlying channel MUST be closed immediately after this packet has been successfully delivered to the client. The router MUST NOT close the client's session (or channel) without sending either a DisconnRply or Disconn packet except in the case of a protocol violation. If a client detects that the router channel has been closed without receiving one of these packets, it should assume network or router failure. A client receiving a redirection via a Disconn MUST attempt to con- nect to the specified router before attempting any other routers for which it has address information. If the channel establishment fails or is refused (via ConnRply), the default router selection process SHOULD be performed. A client MAY perform loop detection for redirection to cater for a misconfiguration of routers redirecting a client indefinitely. If a loop is detected, the default router selection process SHOULD be per- formed. 7.4.8. Security Request Sets the keys associated with the session. Two sets of keys are maintained by the router: those used when sending notifications, and those used for registered subscriptions. This packet allows keys to be added or removed from either or both sets as an atomic operation. Arnold, ed. Expires in 6 months [Page 31] Internet Draft Elvin Client Protocol 4.0 August 2007 struct SecRqst { id32 xid; Keys add_nfn_keys; Keys del_nfn_keys; Keys add_sub_keys; Keys del_sub_keys; }; A client MUST NOT request the addition of a key already registered, or the removal of a key not registered. Such an action is treated as a protocol error. The client's session keys MUST be updated prior to processing any further packets in this session. A notification sent immediately after a SecRqst within the same session MUST match a subscription requiring the updated keys. 7.4.9. Security Reply Sent by the router to clients to confirm a successful change of keys. struct SecRply { id32 xid; }; A router MUST respond to a client's SecRqst by sending a SecRply, if the request was successful, or a Nack if the request was unable to be completed successfully. All notifications and quench notifications delivered within the ses- sion after the SecRply MUST match the changes acknowledged by the SecRply. 7.4.10. QoS Request Sent by clients to the router to request renegotiation of the options for the current session. Legal option names, their semantics, and allowed range of values are defined later in the Connection Options section. The router MAY respond with a Nack if renegotiation is not supported. Otherwise, it MUST respond with a QosRply specifying the active option values following its processing of the request. struct QosRqst { id32 xid; NameValue options[]; }; Arnold, ed. Expires in 6 months [Page 32] Internet Draft Elvin Client Protocol 4.0 August 2007 7.4.11. QoS Reply Sent by the router to inform a client of the active connection options after processing a QosRqst. For a description of the con- tents of the returned options table, see the Connection Options sec- tion below. struct QosRply { id32 xid; NameValue options[]; }; 7.4.12. Drop Warning Sent by routers to clients to indicate that notification packets have been dropped from this place in the data stream due to congestion in the router. Dropped packets MAY include NotifyDeliver, SubAddNotify, SubModNotify and SubDelNotify. struct DropWarn { }; The router may also drop ConnConf packets, but this MUST NOT result in in a DropWarn being sent to the client. As a ConnConf is only sent to confirm the connection between a client and the router is still active, a ConnConf will be dropped if there is any other pend- ing data to be sent ot the client. The client can determine from the fact that other packets have arrived that the connection still works. 7.4.13. Test Connection A client's connection to the Elvin router can be inactive for long periods. This is especially the case for subscribers for whom match- ing messages are seldom generated. Clients and routers MUST imple- ment Test Connection and Confirm Connection packets to allow verifi- cation of connectivity. This application-level functionality is an alternative to a channel level carrier-loss reporting mechanism. If an Elvin channel does not provide support for carrier loss detection, this mechanism can be used. struct TestConn { }; A Test Connection packet MAY be sent by either client or router to verify that the channel remains active after a period during which no packets have been received. If, after a TestConn has been sent, no traffic has been received on the channel within a timeout period, the channel is assumed to have failed and the session MUST be closed as for a protocol violation. Arnold, ed. Expires in 6 months [Page 33] Internet Draft Elvin Client Protocol 4.0 August 2007 A TestConn MAY be sent if no packets have been received within a con- figured timeout period. This period MUST be configurable, sending MUST be able to be disabled, and SHOULD be disabled by default. These restrictions serve to limit the load on routers servicing Test- Conn requests. 7.4.14. Confirm Connection struct ConfConn { }; Clients and routers MUST implement support for ConfConn. A router receiving a TestConn packet MUST queue a ConfConn response if there are no other packets waiting for the client to read. If other packets are waiting for the client to service its connection, the router MUST NOT send the ConfConn (since the client's reading of the other packets will indicate that its connection is active). Routers MAY drop ConfConn packets queued for delivery to a client if there is any other packet about to be sent to the client. The client MUST use use the fact that any packet arriving from the router indi- cates an active connection. Clients MUST send a ConfConn in response to a TestConn from the router. 7.4.15. Notification Emit Sent by client to the Elvin router. There are two possible delivery modes, determining how the router should match supplied security keys. Delivery can be specified as requiring the consumer to have a matching key (deliver_insecure is not set). Alternatively, the pro- ducer can not require that the consumer have a key, but if one or more are supplied, then at least one MUST match (deliver_insecure is set). struct NotifyEmit { NameValue attributes[]; boolean deliver_insecure; Keys keys; }; 7.4.16. Notification Deliver Sent by the Elvin router to a client. Arnold, ed. Expires in 6 months [Page 34] Internet Draft Elvin Client Protocol 4.0 August 2007 struct NotifyDeliver { NameValue attributes[]; id64 secure_matches[]; id64 insecure_matches[]; }; 7.4.17. Subscription Add Request Sent by client to the Elvin router. Requests delivery of notifica- tions which match the supplied subscription expression. struct SubAddRqst { id32 xid; string expression; boolean accept_insecure; Keys keys; }; If successful, the router MUST respond with a SubRply. If the client has registered too many subscriptions, the router MUST return a Nack with the QOS_LIMIT error code. If the router has too many registered subscriptions, or exceeds some other internal limit, it MUST return a Nack with error code IMPL_LIMIT. If the subscription expression fails to parse, the router MUST return a Nack with an appropriate error code. The standard codes are speci- fied in "Subscription Errors" or an implementation specific code MAY be used. 7.4.18. Subscription Modify Request Sent by client to the Elvin router. Update the specified subscrip- tion to request notifications matching a different subscription expression, or to alter the security keys associated with the sub- scription. struct SubModRqst { id32 xid; id64 subscription_id; string expression; boolean accept_insecure; Keys add_keys; Keys del_keys; }; Any (and all) of the expression, add_keys and del_keys field MAY be empty. The accept_insecure field cannot be empty: it must always be set to the required value. If the accept_insecure field value is unchanged from that registered at the router, and all other fields Arnold, ed. Expires in 6 months [Page 35] Internet Draft Elvin Client Protocol 4.0 August 2007 are empty, the modification SHALL be considered successful. A successful modification of the subscription MUST return a SubRply to the client. A Nack, with error code NO_SUCH_SUB, MUST be returned if the sub- scription_id is not valid. If the subscription expression fails to parse, the router MUST return a Nack describing the error. An invalid expression MUST NOT alter the current state of the specified subscription. An attempt either to add a key already associated with the specified subscription or to remove a key not currently associated with the specified subscription MUST be ignored, and the remainder of the operation processed. No indication that any part of the operation was ignored is returned to the client. 7.4.19. Subscription Delete Request Sent by client to the Elvin router. A Nack will be returned if the subscription identifier is not valid. struct SubDelRqst { id32 xid; id64 subscription_id; }; 7.4.20. Subscription Reply Sent from the Elvin router to the client as acknowledgement of a suc- cessful subscription change. struct SubRply { id32 xid; id64 subscription_id; }; 7.4.21. Quench Add Request Sent by clients to the Elvin router. Requests notification of sub- scriptions referring to the specified attributes. struct QnchAddRqst { id32 xid; string names[]; boolean deliver_insecure; Keys keys; }; Arnold, ed. Expires in 6 months [Page 36] Internet Draft Elvin Client Protocol 4.0 August 2007 7.4.22. Quench Modify Request Sent by client to the Elvin router. Requests changes to the list of attribute names associated with a quench identifier. struct QnchModRqst { id32 xid; id64 quench_id; string names_add[]; string names_del[]; boolean deliver_insecure; Keys add_keys; Keys del_keys; }; 7.4.23. Quench Delete Request Sent by client to the Elvin router. Requests that the router no longer notify the client of changes to subscriptions with the associ- ated attribute names. struct QnchDelRqst { id32 xid; id64 quench_id; }; 7.4.24. Quench Reply Sent from the Elvin router to the client as acknowledgement of a suc- cessful quench requirements change (QnchAddRqst, QnchModRqst, QnchDelRqst): struct QnchRply { id32 xid; id64 quench_id; }; 7.4.25. Subscription Add Notification Sent from router to clients to inform them of a new subscription predicate component matching the registered quench attribute name list for each of the identified quench registrations. The secure quench ids represent the quenches whose keys matched the corresponding subscription keys, whereas the insecure quenches did not have matching keys but both the subscription's accept_insecure and the quench's deliver_insecure flags were set. Arnold, ed. Expires in 6 months [Page 37] Internet Draft Elvin Client Protocol 4.0 August 2007 struct SubAddNotify { id64 secure_quench_ids[]; id64 insecure_quench_ids[]; id64 term_id; SubAST sub_expr; }; 7.4.26. Subscription Modify Notification This packet indicates that a subscription predicate component match- ing their registered quench attribute name list changed for each of the identified quench registrations. Note that a subscription term that had a key replaced might no longer match a particular quench registeration. This is notified using a SubDelNotify. Similarly a key replacement might cause a SubAddNotify if its key list now intersects with that of a registered quench request. struct SubModNotify { id64 secure_quench_ids[]; id64 insecure_quench_ids[]; id64 term_id; SubAST sub_expr; }; 7.4.27. Subscription Delete Notification Sent from router to clients to inform them of the removal of a sub- scription predicate component that had matched their registered attribute name list for each of the identified quench registrations. struct SubDelNotify { id64 quench_ids[]; id64 term_id; }; 7.5. Connection Options Connection options control the behaviour of the router for the speci- fied connection. They may be set during connection establishment and modified during the life of the connection. At the point of connection, the client may submit a set of requested option values in its ConnRqst packet. The router evaluates the client's request, and returns a set of proposed option values in the ConnRply packet. Once a connection is established, the client can request a modification of the connection options by sending a QosRqst packet. The router's response is delivered in a QosReply packet. The router evaluates received connection options requests, and for Arnold, ed. Expires in 6 months [Page 38] Internet Draft Elvin Client Protocol 4.0 August 2007 each option requested, the router MUST either a) Understand and accept the requested value. The ConnRply/QosRply options table MUST contain an entry for this option, and its value MUST be that requested. Or, b) Understand but reject the requested value. The ConnRply/QosRply options table MUST contain an entry for this option. Its value MUST NOT match the request, but MUST be that which the router is prepared to provide. Or, c) Not recognise the requested option. The ConnRply/QosRply options table MUST NOT contain an entry for this option. A router implementation MAY add entries to the ConnRply/QosRply options tables that do not reflect options requested by the client. A client implementation, upon receiving a ConnRply, SHOULD enable the client application to examine the offered option values. The appli- cation SHOULD be able to reject the connection if the offered options are unsatisfactory. On receiving a QosRply, a client implementation SHOULD enable the client application to examine the revised options. If they are not satisfactory, the client SHOULD be able to close the connection. A router implementation MUST support the following options. Name | Type ----------------------------+-------- Attribute.Max-Count | int32 Attribute.Name.Max-Length | int32 Attribute.Opaque.Max-Length | int32 Attribute.String.Max-Length | int32 Packet.Max-Length | int32 Receive-Queue.Drop-Policy | string Receive-Queue.Max-Length | int32 Send-Queue.Drop-Policy | string Send-Queue.Max-Length | int32 Subscription.Max-Count | int32 Subscription.Max-Length | int32 ----------------------------+-------- A router implementation SHOULD return the following options. Name | Type ----------------------------+-------- Supported-Key-Schemes | string Vendor-Identification | string ----------------------------+-------- Arnold, ed. Expires in 6 months [Page 39] Internet Draft Elvin Client Protocol 4.0 August 2007 7.5.1. Option Semantics Attribute.Max-Count Maximum number of attributes in a notification. The minumum value supported by an implementation SHOULD be at least 16. Attribute.Name.Max-Length Maximum length, in bytes, of an attribute name. The minimum value supported by an implementation SHOULD be at least 64. Attribute.Opaque.Max-Length Maximum length, in bytes, for opaque val- ues. The minimum value supported by an implementation SHOULD be at least 1024. Attribute.String.Max-Length Maximum length, in bytes, for opaque values. Note that this value is not the number of characters: some characters may take up to 5 bytes to respresent using the require UTF-8 encoding. The minimum value supported by an implementation SHOULD be at least 1024. Packet.Max-Length Maximum length, in bytes, of a marshalled packet. The minimum value SHOULD be at least 1024. Receive-Queue.Drop-Policy It is expected that most router implementations will maintain a queue of packets received from a client prior to processing them. This property describes the desired behaviour of this packet queue if it exceeds the negotitated maximum size. A packet queue implementation SHOULD distinguish between packets that, if discarded, would cause a protocol error, and those that can be discarded without losing state synchronisation between the client and the router: NotifyDeliver, SubAddNotify, SubModNotify, and Sub- DelNotify. A router implementation SHOULD support the following drop policy val- ues: oldest newest largest none If a router implementation does not use a queue for received packets, it MUST accept any legal value for this property. Receive-Queue.Max-Length This property sets a maximum size of the router's per-client incoming packet queue, in bytes. If the queue exceeds this size, the router SHOULD drop one or more packets, according to the queue's drop pol- icy. If a router implementation does not use a queue for received packets, it MUST accept any legal value for this property. Send-Queue.Drop-Policy It is expected that most router implementations will maintain, for each connected client, a queue of packets for delivery. This Arnold, ed. Expires in 6 months [Page 40] Internet Draft Elvin Client Protocol 4.0 August 2007 property describes the desired behaviour of this packet queue if it exceeds the negotitated maximum size. See the description of the receive queue drop policy. Send-Queue.Max-Length See the description of the receive queue maximum length. Subscription.Max-Count This numeric option specifies the maximum number of subscriptions that may be registered by a client. Subscription.Max-Length This numeric option specifies the maximum allowed length, in bytes, of a subscription expression registered with the router. Supported-Key-Schemes A router implementation may support various key schemes for the con- trol of Elvin message delivery. This string property contains the list of key schemes names, separated by the ASCII space character, supported by the router. Clients MAY request their required schemes, but regardless, a router implementation SHOULD always include the set of supported schemes in its ConnRply options table. 7.5.2. Additional Options A router implementation MAY support additional, implementation-spe- cific options. The name and semantics of a non-standard option SHOULD be registered with elvin.org to enable other implementations to adopt or avoid it. 7.5.3. Compatibility One popular Elvin implementation uses non-standard names for its con- nection options. In the interests of compatibility, implementations MAY provide special handling for these options. Arnold, ed. Expires in 6 months [Page 41] Internet Draft Elvin Client Protocol 4.0 August 2007 Standard Name | Compatibility Name ----------------------------+------------------------------------ Attribute.Max-Count | router.attribute.max-count Attribute.Name.Max-Length | router.attribute.name.max-length Attribute.Opaque.Max-Length | router.attribute.opaque.max-length Attribute.String.Max-Length | router.attribute.string.max-length Packet.Max-Length | router.packet.max-length Receive-Queue.Drop-Policy | router.recv-queue.drop-policy Receive-Queue.Max-Length | router.recv-queue.max-length Send-Queue.Drop-Policy | router.send-queue.drop-policy Send-Queue.Max-Length | router.send-queue.max-length Subscription.Max-Count | router.subscription.max-count Subscription.Max-Length | router.subscription.max-length Supported-Key-Schemes | router.supported-keyschemes Vendor-Identification | router.vendor-identification ----------------------------+------------------------------------ 8. PROTOCOL IMPLEMENTATION The abstract protocol described in the previous section may be imple- mented by multiple concrete protocols. The concrete protocols used to establish a channel can be specified at run time, and selected from the intersection of those offered by the client and router-side implementations. 8.1. Layering and Modules A channel supporting the Elvin protocol can be comprised of multiple, layered components, referred to as protocol modules. These modules are layered to form a protocol stack, providing the channel over which the abstract protocol packets are carried. The combined stack MUST provide marshalling and data transport facil- ities, and MAY provide other features. 8.2. Standard Protocol overview: TCP/SSL, XDR Elvin4 supports a 3-layer protocol stack, providing separate mar- shalling, security and transport options. While the content of the resulting data packets composed by each of these layers is specified by this document, the programming interfaces are internal to an implementation. An Elvin4 implementation MAY support any number of distinct combina- tions of protocols. An Elvin4 implementation MUST support the stan- dard protocol stack comprised of XDR marshalling, SSL-3 security and TCP/IP transport. This combination is known as the Elvin4 standard protocol. Arnold, ed. Expires in 6 months [Page 42] Internet Draft Elvin Client Protocol 4.0 August 2007 Additional protocol layers must be proposed and registered via the IETF RFC series, either as a revision to this document, or as a sepa- rate specification. 8.2.1. TCP Protocol The default Elvin transport module uses a TCP connection to link clients with an Elvin router. Elvin routers offer a TCP endpoint, at a particular port. The IANA- assigned port number for Elvin client protocol is 2917. Clients ini- tiate the TCP connection to the router's host and port. The abstract protocol requires that packet boundaries are preserved. Since TCP provides a stream-oriented protocol, an additional layer of framing must be implemented to support this requirement. Each packet, passed to the TCP module from higher layer(s) in the stack, is sent preceded by a 4-octet framing header. The header value is an unsigned 2's complement integer in network byte order, specifying the length of the contained packet in octets. 0 1 2 3 +---+---+---+---+---+---+---+...+---+---+---+ | length | packet data | FRAMED PACKET +---+---+---+---+---+---+---+...+---+---+---+ The receiving side of the connection should first read the header, record the expected length, and then read until the complete packet is received. An implementation MAY limit the size of packets it is willing to receive. After reading a header preceding a packet exceeding that length, the implementation MUST reset the TCP connection. Note that the use of a 4 octet header puts an upper limit on this size. Elvin clients SHOULD negotiate the maximum packet length during connection. An open TCP connection may be closed only between the last byte of packet data, and the following framing header. If the connection is lost mid-packet, it MUST be reported to the abstract protocol layer as a communications error. 8.2.1.1. Protocol Options An implementation of the TCP protocol SHOULD support a connection option to control the use of Nagle's algorithm (normally implemented as the TCP_NODELAY socket option). Name | Type ----------------------------+-------- TCP.Send-Immediately | int32 Arnold, ed. Expires in 6 months [Page 43] Internet Draft Elvin Client Protocol 4.0 August 2007 The value should be set to zero to enable Nagle's algorithm, and non- zero to request that it be disabled. 8.2.1.2. Use of Proxies In some environments, it is necessary to use proxy services to cir- cumvent firewall policies that would otherwise block Elvin protocol connections. Lest we be misunderstood, this practice is NOT RECOM- MENDED. Having said that, the prevalence of administrative policy requiring such breakage is such that Elvin TCP protocol modules SHOULD support establishment of connections via HTTP proxies, SHOULD support basic authentication and MAY support alternative authentication mechanisms. A proxy connection is established by connecting first to an endpoint offered by the proxy router, and requesting that it tunnel further data on the connection to the specified Elvin router endpoint. This request takes the form of CONNECT host.example.com HTTP/1.1 Proxy-Authorization: Basic XXXXXX with the optional parameter lines terminated by a blank line. The client then waits for a response from the proxy router, indicat- ing whether its request was successful. The response from the proxy router consists of CRLF-delimited lines of text, terminated by a blank line. Note that this text can be a substantial length. The text is a properly formatted HTTP response, and should be parsed according to XXX. Common response codes are 200, 404 and 407. As an example, HTTP/1.0 200 Connection established is a successful response. 8.2.2. Security null 8.2.3. Marshalling The standard Elvin 4 marshalling uses XDR [RFC1832] to encode data. Messages sent between the a client and and Elvin router are encoded as a sequence of encoded XDR types. This section uses diagrams to illustrate clearly certain segment and packet layouts. In most illustrations, each box (delimited by a plus Arnold, ed. Expires in 6 months [Page 44] Internet Draft Elvin Client Protocol 4.0 August 2007 sign at the 4 corners and vertical bars and dashes) depicts a 4 byte block as XDR is 4 byte aligned. Ellipses (...) between boxes show zero or more additional bytes where required. Some packet diagrams extend over multiple lines. In these cases, '>>>>' at the end of the line indicates continuation to the next line and '<<<<' at the begin- ning of a line indicates a segment has some preceding blocks on the previous line. Numbers used along the top line of packet diagrams indicate byte lengths. +---------+---------+---------+...+---------+ | block 0 | block 1 | block 2 |...|block n-1| PACKET +---------+---------+---------+...+---------+ 8.2.3.1. Packet Identification The abstract packet descriptions deliberately leave the method for identifying packets to the concrete encoding. For XDR, each packet is identified by the pkt_id enumeration below: enum { UNotify = 32, Nack = 48, ConnRqst = 49, ConnRply = 50, DisconnRqst = 51, DisconnRply = 52, Disconn = 53, SecRqst = 54, SecRply = 55, NotifyEmit = 56, NotifyDeliver = 57, SubAddRqst = 58, SubModRqst = 59, SubDelRqst = 60, SubRply = 61, DropWarn = 62, TestConn = 63, ConfConn = 64, QosRqst = 70, QosRply = 71, QnchAddRqst = 80, QnchModRqst = 81, QnchDelRqst = 82, QnchRply = 83, SubAddNotify = 84, SubModNotify = 85, SubDelNotify = 86 } pkt_id; In XDR, enumerations are marshalled as 32 bit integral values. For Elvin, each packet marshalled using XDR starts with a value from the above pkt_id enumeration. The format for the remainder of the packet is then specific to the value of the packet identifer. 0 1 2 3 +---+---+---+---+---+---+---+...+---+---+---+ | pkt_id | remainder | ENCODED PACKET +---+---+---+---+---+---+---+...+---+---+---+ |<---header---->|<-----------data---------->| Note that the XDR marshalling layer does NOT indicate the length of the packet. This is left to the underlying transport layer being used. For example, a UDP transport could use the fact that a datagram Arnold, ed. Expires in 6 months [Page 45] Internet Draft Elvin Client Protocol 4.0 August 2007 contains the length of data in the packet. 8.2.3.2. Base Types The Elvin protocol relies on seven basic types used to construct each packet: boolean, uint8, int32, int64, real64, string, byte[]. Below is a summary of how these types are represented when using XDR encoding. Each datatype used in the abstract descriptions of the packets has a mapping to a corresponsing XDR data type as defined in [RFC1832]. ------------------------------------------------------------------- Elvin Type XDR Type Encoding Summary ------------------------------------------------------------------- boolean bool 4 bytes, last byte is 0 or 1 uint8 unsigned int 4 bytes, last byte has value int32 int 4 bytes, MSB first int64 hyper 8 bytes, MSB first real64 double 64-bit double precision float string string 4 byte length, UTF8 encoded string, zero padded to next four byte boundary byte[] variable- 4 byte length, data, zero padded to next length opaque four byte boundary ------------------------------------------------------------------- When the type of following data needs to be described in a packet (eg, the value in a name-value pair used in NotifyEmit packets), one of the base type ID's is encoded as an XDR enumeration. This is often needed when a value in a packet is one of a number of possible types. In these cases, the encoded value is preceded a type code from the following enumeration: enum { xdr_int32 = 1, xdr_int64 = 2, xdr_real64 = 3, xdr_string = 4, xdr_opaque = 5 } value_typecode; Note that the above enumeration does not include all of the datatypes used in the protocol. It only describes data which can be contained in the abstract Value segment of a packet. A Value in an encoded packet is thus typed by prepending four bytes which encode the type code: Arnold, ed. Expires in 6 months [Page 46] Internet Draft Elvin Client Protocol 4.0 August 2007 0 1 2 3 +--+--+--+--+--+--+--+--+...+--+--+--+--+ | typecode | value | TYPED VALUE +--+--+--+--+--+--+--+--+...+--+--+--+--+ |<--enum--->|<--format depends on enum--> For illustration, if an int64 of value 1024L is preceded by its type for marshalling, it would be sent as four bytes for the type id of 2 and eight bytes for the value. 0 1 2 3 4 5 6 7 8 9 10 11 +--+--+--+--+--+--+--+--+--+--+--+--+ | 0x02 | 0x0400 | INT64 EXAMPLE +--+--+--+--+--+--+--+--+--+----+---+ |<--enum--->|<--------hyper-------->| 8.2.3.3. Encoding Arrays All arrays in the abstract protocol are of variable length. Arrays of objects are encoded by prepending the length of the array as an int32 - the items are in the array are then each encoded in sequence starting at item 0. The 32bit length places a theoretical limit of (2**32) - 1 items per list. In practice, implementations are expected to have much lower maxima for the number of items in a list transmitted per packet. For example, an implemenation may restrict the number of fields in a notification to 1024. Such limitations SHOULD be documented for each implemenation. Service offers and con- nection replys SHOULD also provide such limitations. See the section X on Connection Establishment. 0 1 2 3 +--+--+--+--+--+--+--+--+--+--+--+--+...+--+--+--+--+ | n | item 0 | item 1 |...| item n-1 | ARRAY +--+--+--+--+--+--+--+--+--+--+--+--+...+--+--+--+--+ |<--int32-->|<----------------n items-------------->| For illustration, *** FIXME *** .... 0 4 8 12 +--+--+--+--+--+--+--+--+--+--+--+--+ | 0x01 | 0x400 | ARRAY EXAMPLE +--+--+--+--+--+--+--+--+--+----+---+ |<--enum--->|<--------hyper-------->| 8.2.3.4. Subscription Abstract Syntax Trees Arnold, ed. Expires in 6 months [Page 47] Internet Draft Elvin Client Protocol 4.0 August 2007 enum { empty_tc = 0, name_tc = 1, int32_tc = 2, int64_tc = 3, real64_tc = 4, string_tc = 5, equals_tc = 8, not_equals_tc = 9, less_than_tc = 10, less_than_equals_tc = 11, greater_than_tc = 12, greater_than_equals_tc = 13, or_tc = 16, xor_tc = 17, and_tc = 18, not_tc = 19, unary_plus_tc = 20, unary_minus_tc = 21, multiply_tc = 22, divide_tc = 23, modulo_tc = 24, add_tc = 25, subtract_tc = 26, shift_left_tc = 27, shift_right_tc = 28, logical_shift_right_tc = 29, bit_and_tc = 30, bit_xor_tc = 31, bit_or_tc = 32, bit_negate_tc = 33, func_int32_tc = 40, func_int64_tc = 41, func_real64_tc = 42, func_string_tc = 43, func_opaque_tc = 44, func_nan_tc = 45, func_begins_with_tc = 48, func_contains_tc = 49, func_ends_with_tc = 50, func_wildcard_tc = 51, func_regex_tc = 52, func_fold_case_tc = 56, func_decompose_tc = 57, func_decompose_compat_tc = 58, Arnold, ed. Expires in 6 months [Page 48] Internet Draft Elvin Client Protocol 4.0 August 2007 func_require_tc = 64, func_equals_tc = 65, func_size_tc = 66 } subast_typecode; 8.2.3.5. Packet Encoding Example An Elvin notification is a list of name-value pairs, where the value is one of the five base types of int32, int64, real64, string and opaque. The encoding of these pairs must also include the data type for the value. For both the NotifyEmit and the NotifyDeliver pack- ets, we introduce a name-type-value (NTV) block used to encode a notification attribute. The name of an attribute is always encoded as an XDR string. The type is an enumeration of five different values indicating one of int32, int64, real64, string or opaque (byte array). The value, encoded as a standard XDR type, is determined by the preceding type. On the wire, a name-value is laid out as follows: +------+...+------+------+------+...+------+ | name | type | value | NAME-TYPE-VALUE +------+...+------+------+------+...+------+ name (string) name of this attribute type (enum) type of the encoded value. 0ne of int32, int64, real64, string or opaque value - the encoded value for this attribute. Notifications begin with the number of attributes as an int32. 0 4 8 12 ... +------+------+------+...+------+...+------+...+------+ |pkt id|len n | ntv 0 | | ntv n-1 | >>>> +------+------+------+...+------+...+------+...+------+ |<----------n name-type-values--------->| +------+------+...+------+...+------+...+------+ <<<< |len m | key 0 | | key m-1 | +------+------+...+------+...+------+...+------+ |<----------------m keys--------------->| NOTIFICATION Arnold, ed. Expires in 6 months [Page 49] Internet Draft Elvin Client Protocol 4.0 August 2007 pkt id (enum) packet type for NotifyEmit len n (int32) number of name-type-value triples in the notification. n MUST be greater than zero. ntv x [block] encoded as a name-type-value triple, described above. There MUST be n name-type-value blocks where n > 0. len m (int32) number of security keys in the notification key x (opaque) uninterpreted bytes of a security key. There MUST be m keys where m >= 0. 8.3. Environment ports location service names environment variables file usage - /etc/elvind.conf - /etc/slp.conf registry 9. SECURITY CONSIDERATIONS 10. IANA CONSIDERATIONS protocol module names key mechanism identifiers Arnold, ed. Expires in 6 months [Page 50] Internet Draft Elvin Client Protocol 4.0 August 2007 11. APPENDIX A - ELVIN SUBSCRIPTION LANGUAGE The Elvin subscription language is used by clients to select notifi- cations for delivery. This section documents the formal syntax for the language. Subscription expressions are normally represented as strings in the programming language of the client application. These strings SHOULD allow the entry of the full Unicode character set, either directly or through an escaping mechanism. The subscription string MUST be encoded as Unicode UTF-8 prior to transmission by the client library. While full Unicode strings are required, they are only used within the language for representing string literals. Attribute names are restricted to a subset of the ASCII character set. The specification is written using ABNF [RFC2234]. ; Elvin subscription language ; ; version: 4.0 ; ; expressions ; sub-exp = sub-exp bool-op sub-exp / bool-exp bool-exp = value "==" value / value "!=" value / value "<" value / value "<=" value / value ">" value / value ">=" value / bool-function-exp / "!" bool-exp / "(" sub-exp ")" value = string-literal / math-exp math-exp = math-exp math-op math-exp / num-value num-value = num-literal / name / function-exp / unary-math-op num-value / "(" value ")" name = id-literal Arnold, ed. Expires in 6 months [Page 51] Internet Draft Elvin Client Protocol 4.0 August 2007 bool-function-exp = bool-pred "(" name ")" function-exp = function-pred "(" args ")" args = arg *( "," arg ) arg = name / string-literal / num-literal ; ; predicates ; bool-pred = "require" / "int32" / "int64" / "real64" / "string" / "opaque" / "nan" function-pred = "begins-with" / "ends-with" / "contains" / "wildcard" / "regex" / "equals" / "size" / "fold-case" / "decompose" / "decompose-compat" ; ; operators ; bool-op = "&&" / "^^" / "||" math-op = "&" / "^" / "|" / "<<" / ">>" / ">>>" / "+" / "-" / "*" / "/" / "%" unary-math-op = "+" | "-" | "~" ; ; literals ; string-literal = DQUOTE 0*(string-char / quote) DQUOTE / quote 0*(string-char / DQUOTE) quote string-char = safe-utf8-char / backslash safe-utf8-char / magic-char magic-char = backslash DQUOTE / backslash quote / backslash backslash safe-utf8-char = %x01-21 / %x23-26 / %x28-5b / %x5d-fd ; not single quote, double quote or backslash Arnold, ed. Expires in 6 months [Page 52] Internet Draft Elvin Client Protocol 4.0 August 2007 num-literal = int32-literal / int64-literal / real64-literal int32-literal = decimal-literal / octal-literal / hex-literal int64-literal = int32-literal "l" ; ABNF is case insensitive so this includes "L" real64-literal = 1*DIGIT "." 1*DIGIT [exponent] exponent = "e" [ "+" | "-" ] 1*DIGIT ; ABNF is case insensitive so this includes "E" backslash = %x5c quote = %x27 id-literal = id-first 0*id-char id-first = ALPHA / "_" / backslash safe-utf8-char id-char = %x21 / %x23-26 / %x28 / %x2a-2b / %x2d-5a / %5e-ff / backslash safe-utf8-char owsp = 0*swsp wsp = 1*swsp swsp = SP / HTAB / CR / LF Arnold, ed. Expires in 6 months [Page 53] Internet Draft Elvin Client Protocol 4.0 August 2007 12. REFERENCES [ERDP] Arnold, D., Boot, J., Phelps, T., Segall, B., "Elvin Router Discovery Protocol", Work in progress [ERCP] Arnold, D., Boot, J., Phelps, T., "Elvin Router Cluster- ing Protocol", Work in progress [ERFP] Arnold, D., Lister, I., "Elvin Router Federation Proto- col", Work in progress [RLM] Arnold, D., Boot, J., "Reliable Local Multicast" Work in progress [RFC1832] Srinivasan, R., "XDR: External Data Representation Stan- dard", RFC 1832, August 1995. [RFC2234] Crocker, D., Overell, P., "Augmented BNF for Syntax Spec- ifications: ABNF", RFC 2234, November 1997. [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC 2279, January 1998. [UNICODE] Unicode Consortium, The, "The Unicode Standard, Version 3.0", Addison-Wesley, 2000. [POSIX.1] IEEE, "POSIX.1-1990", 1990. 13. CONTACT Author's Addresses David Arnold Julian Boot Michael Henderson Ian Lister Ted Phelps Bill Segall Email: specs@elvin.org Arnold, ed. Expires in 6 months [Page 54] Internet Draft Elvin Client Protocol 4.0 August 2007 14. FULL COPYRIGHT STATEMENT Copyright (C) 1999-2007 Elvin.Org All Rights Reserved. This specification may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, record- ing, or by any information storage or retrieval system, providing that the content remains unaltered, and that such distribution is under the terms of this licence. While every precaution has been taken in the preparation of this specification, Elvin.Org assumes no responsibility for errors or omissions, or for damages resulting from the use of the information herein. Elvin.Org welcomes comments on this specification. Please address any queries, comments or fixes (please include the name and version of the specification) to the address below: Email: specs@elvin.org Arnold, ed. Expires in 6 months [Page 55]