Open Pluggable Edge Services A. Rousskov Internet-Draft The Measurement Factory Expires: April 26, 2004 October 27, 2003 OPES Callout Protocol Core draft-ietf-opes-ocp-core-02 Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http:// www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on April 26, 2004. Copyright Notice Copyright (C) The Internet Society (2003). All Rights Reserved. Abstract This document specifies Open Pluggable Edge Services (OPES) Callout Protocol (OCP). OCP is an application-agnostic protocol that facilitates exchange of application messages between an OPES processor and a callout server, for the purpose of adaptation of application messages at the callout server. Rousskov Expires April 26, 2004 [Page 1] Internet-Draft OPES Callout Protocol Core October 2003 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 4 1.1 Scope . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.2 Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 2. Overall Operation . . . . . . . . . . . . . . . . . . . . 7 2.1 Initialization . . . . . . . . . . . . . . . . . . . . . . 7 2.2 Original Dataflow . . . . . . . . . . . . . . . . . . . . 7 2.3 Adapted Dataflow . . . . . . . . . . . . . . . . . . . . . 7 2.4 Termination . . . . . . . . . . . . . . . . . . . . . . . 8 2.5 Exchange Patterns . . . . . . . . . . . . . . . . . . . . 8 2.6 OCP Environment . . . . . . . . . . . . . . . . . . . . . 9 3. Messages . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.1 Message Format . . . . . . . . . . . . . . . . . . . . . . 10 3.2 Message Rendering . . . . . . . . . . . . . . . . . . . . 11 3.3 Message Examples . . . . . . . . . . . . . . . . . . . . . 12 3.4 Message Names . . . . . . . . . . . . . . . . . . . . . . 13 4. Transactions . . . . . . . . . . . . . . . . . . . . . . . 14 5. Invalid input . . . . . . . . . . . . . . . . . . . . . . 15 6. Negotiation . . . . . . . . . . . . . . . . . . . . . . . 16 7. Capability and State Inquiry . . . . . . . . . . . . . . . 18 8. 'Data Recycling' Optimization . . . . . . . . . . . . . . 19 9. 'Out Of The Loop' Optimization . . . . . . . . . . . . . . 21 10. Message Parameters . . . . . . . . . . . . . . . . . . . . 22 10.1 Type Declaration Mnemonic . . . . . . . . . . . . . . . . 22 10.2 Parameter Types . . . . . . . . . . . . . . . . . . . . . 23 10.2.1 Uri . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 10.2.2 Uni . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 10.2.3 Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 10.2.4 Boolean . . . . . . . . . . . . . . . . . . . . . . . . . 24 11. Parameter Definitions . . . . . . . . . . . . . . . . . . 25 11.1 xid . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 11.2 rid . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 11.3 service . . . . . . . . . . . . . . . . . . . . . . . . . 25 11.4 services . . . . . . . . . . . . . . . . . . . . . . . . . 25 11.5 sg-id . . . . . . . . . . . . . . . . . . . . . . . . . . 26 11.6 am-id . . . . . . . . . . . . . . . . . . . . . . . . . . 26 11.7 size-request . . . . . . . . . . . . . . . . . . . . . . . 26 11.8 offset . . . . . . . . . . . . . . . . . . . . . . . . . . 26 11.9 modp . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 11.10 result . . . . . . . . . . . . . . . . . . . . . . . . . . 26 11.11 feature . . . . . . . . . . . . . . . . . . . . . . . . . 28 12. Message Definitions . . . . . . . . . . . . . . . . . . . 29 12.1 Connection Start (CS) . . . . . . . . . . . . . . . . . . 29 12.2 Connection End (CE) . . . . . . . . . . . . . . . . . . . 30 12.3 Create Service Group (SGC) . . . . . . . . . . . . . . . . 31 12.4 Destroy Service Group (SGD) . . . . . . . . . . . . . . . 32 12.5 Transaction Start (TS) . . . . . . . . . . . . . . . . . . 32 Rousskov Expires April 26, 2004 [Page 2] Internet-Draft OPES Callout Protocol Core October 2003 12.6 Transaction End (TE) . . . . . . . . . . . . . . . . . . . 33 12.7 Application Message Start (AMS) . . . . . . . . . . . . . 33 12.8 Application Message End (AME) . . . . . . . . . . . . . . 34 12.9 Data Use Mine (DUM) . . . . . . . . . . . . . . . . . . . 34 12.10 Data Use Yours (DUY) . . . . . . . . . . . . . . . . . . . 36 12.11 Data Won't Send Yours (DWSY) . . . . . . . . . . . . . . . 36 12.12 Data Won't Look At Yours (DWLY) . . . . . . . . . . . . . 37 12.13 Data Want Out (DWO) . . . . . . . . . . . . . . . . . . . 38 12.14 Data Pause (data-pause) . . . . . . . . . . . . . . . . . 38 12.15 Data Paused (data-paused) . . . . . . . . . . . . . . . . 39 12.16 Data Need (data-need) . . . . . . . . . . . . . . . . . . 40 12.17 Data ACK (DACK) . . . . . . . . . . . . . . . . . . . . . 40 12.18 I Am Here (pong) . . . . . . . . . . . . . . . . . . . . . 41 12.19 Are You There? (ping) . . . . . . . . . . . . . . . . . . 42 12.20 Negotiation Offer (NO) . . . . . . . . . . . . . . . . . . 42 12.21 Negotiation Response (NR) . . . . . . . . . . . . . . . . 43 12.22 I Support (i-can) . . . . . . . . . . . . . . . . . . . . 44 12.23 Can You Support (can-you) . . . . . . . . . . . . . . . . 44 12.24 I Currently Use (i-do) . . . . . . . . . . . . . . . . . . 45 12.25 Do You Currently Use (do-you) . . . . . . . . . . . . . . 45 13. Application Protocol Requirements . . . . . . . . . . . . 46 14. IAB Considerations . . . . . . . . . . . . . . . . . . . . 47 15. Security Considerations . . . . . . . . . . . . . . . . . 48 16. Compliance . . . . . . . . . . . . . . . . . . . . . . . . 50 17. To-do . . . . . . . . . . . . . . . . . . . . . . . . . . 51 A. Acknowledgements . . . . . . . . . . . . . . . . . . . . . 53 B. Change Log . . . . . . . . . . . . . . . . . . . . . . . . 54 Normative References . . . . . . . . . . . . . . . . . . . 61 Informative References . . . . . . . . . . . . . . . . . . 62 Author's Address . . . . . . . . . . . . . . . . . . . . . 62 Intellectual Property and Copyright Statements . . . . . . 63 Rousskov Expires April 26, 2004 [Page 3] Internet-Draft OPES Callout Protocol Core October 2003 1. Introduction The Open Pluggable Edge Services (OPES) architecture [I-D.ietf-opes-architecture], enables cooperative application services (OPES services) between a data provider, a data consumer, and zero or more OPES processors. The application services under consideration analyze and possibly transform application-level messages exchanged between the data provider and the data consumer. The OPES processor can delegate the responsibility of service execution by communicating with remote callout servers. As described in [I-D.ietf-opes-protocol-reqs], an OPES processor communicates with and invokes services on a callout server by using a callout protocol. This document specifies the core of such a protocol. OCP Core specification documents general, application-independent protocol mechanisms. A separate series of documents describe application-specific aspects of OCP. For example, "HTTP adaptation with OPES" [I-D.ietf-opes-http] describes, in part, how HTTP messages and HTTP meta-information can be communicated over OCP. 1.1 Scope As an application proxy, OPES processor proxies a single application protocol or converts from one application protocol to another. At the same time, OPES processor may be an OCP client, using OCP to facilitate adaptation of proxied messages at callout servers. It is therefore natural to assume that OPES processor takes application messages being proxied, passes them over OCP to callout servers, and then puts the adaptation results back on the wire. However, such an assumption implies that OCP is applied directly to application messages that OPES processor is proxing, which may not be the case. OPES processor scope callout server scope +-----------------+ +-----------------+ | pre-processing | OCP scope | | | +- - - - - - - - - - - - - - - - - - -+ | | iteration | <== ( application data ) ==> | adaptation | | +- - - - - - - - - - - - - - - - - - -+ | | post-processing | | | +-----------------+ +-----------------+ Figure 1 OPES processor may preprocess (or postprocess) proxied application messages before (or after) they are adapted at callout servers. For example, a processor may take an HTTP response being proxied and pass Rousskov Expires April 26, 2004 [Page 4] Internet-Draft OPES Callout Protocol Core October 2003 it as is, along with metadata about the corresponding HTTP connection. Another processor may take an HTTP response, extract its body, and pass that body, along with the content-encoding metadata. Moreover, to perform adaptation, OPES processor may execute several callout services, iterating over several callout servers. Such preprocessing, postprocessing, and iterations make it impossible to rely on any specific relationship between application messages being proxied and application messages being sent to a callout service. Similarly, specific adaptation actions at the callout server are outside of OCP Core scope. This specification does not define or require any specific relationship among application messages being proxied by the OPES processor and application messages being exchanged with callout servers via OCP. OPES processor usually provides some mapping among these application messages, but processor's specific actions are beyond OCP scope. In other words, this specification is not concerned with the OPES processor role as an application proxy, or as an iterator of callout services. The scope of OCP Core is communication between a single OPES processor and a single callout server. Furthermore, an OPES processor is at liberty to choose which proxied application messages or information about them to send over OCP. All proxied messages on all proxied connections (if connections are defined for a given application protocol), everything on some connections, selected proxied messages, or nothing might be sent over OCP to callout servers. OPES processor and callout server state related to proxied protocols can be relayed over OCP as application message metadata. 1.2 Terminology The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. When used with the normative meanings, these keywords will be all uppercase. Occurrences of these words in lowercase comprise normal prose usage, with no normative implications. OPES processor works with messages from application protocols and may relay information about those application messages to a callout server. OCP is also an application protocol. Thus, protocol elements like "message", "connection", or "transaction" exist in OCP and other application protocols. In this specification, all references to elements from application protocols other than OCP are used with an explicit "application" qualifier. References without the "application" qualifier, refer to OCP elements. Rousskov Expires April 26, 2004 [Page 5] Internet-Draft OPES Callout Protocol Core October 2003 OCP message: OCP message is a basic unit of communication between an OPES processor and a callout server. Message is a sequence of octets formatted according to syntax rules (Section 3.1). Message semantics is defined in Section 12. application message: An entity defined by OPES processor and callout server negotiation. Usually, the negotiated definition would match the definition from an application protocol (e.g., [RFC2616] definition of an HTTP message, including headers, and body). application message data: An opaque sequence of octets representing complete or partial application message. OCP Core does not distinguish application message structure (if any). Application message data may be empty. data: Same as application message data. original Referring to application message flowing from the OPES processor to a callout server. adapted Referring to application message flowing from an OPES callout server to the OPES processor. adaptation: Any kind of access by a callout server, including modification and copying. For example, translating or logging an SMTP message is adaptation of that application message. agent: Client or server for a given communication protocol. A proxy is both a client and a server and, hence, also an agent. For example, OPES processor and callout server are OCP agents. immediate: Performing the specified action before reacting to new incoming messages or sending any new messages unrelated to the specified action. OCP extension: A specification extending or adjusting this document to cover an application protocol (a.k.a., application binding, e.g., [I-D.ietf-opes-http]), new OCP functionality (e.g., transport encryption and authentication), and/or new OCP Core version. Rousskov Expires April 26, 2004 [Page 6] Internet-Draft OPES Callout Protocol Core October 2003 2. Overall Operation OPES processor may use OPES callout protocol (OCP) to communicate with callout servers. Adaptation using callout services is sometimes called a "bump in the wire" architecture. 2.1 Initialization OPES processor establishes transport connections with callout servers for the purpose of exchanging application messages with the callout server(s) using OCP. After a transport-layer connection (usually TCP/ IP) is established, communicating OCP agents exchange Connection Start (CS (Section 12.1)) messages. Next, OCP features can be negotiated between the processor and the callout server (see Section 6). For example, OCP agents have to agree on transport encryption and application message definition. When enough settings are negotiated, OCP agents may start exchanging application messages. 2.2 Original Dataflow When OPES processor wants to adapt an application message, the OPES processor sends a Transaction Start (TS (Section 12.5)) message to initiate an OCP transaction dedicated to that application message. The processor then sends an Application Message Start (AMS (Section 12.7)) message to prepare the callout server for application data that will follow. Once application message scope is established, application data can be sent to the callout server, using Data Use Mine (DUM (Section 12.9)) and related OCP message(s). All these messages correspond to the original dataflow. 2.3 Adapted Dataflow The callout server receives data and metadata sent by the OPES processor (original data flow). The callout server analyses metadata and adapts data as it comes in. The server usually builds its version of metadata and responds to OPES processor with an 'app-message-start' message. Adapted application message data can be sent next, using Data Use Mine (DUM (Section 12.9)) OCP message(s). The application message is then announced to be "completed" or "closed" using an Application Message End (AME (Section 12.8)) message. The transaction may be closed using a Transaction End (TE (Section 12.6)) message as well. All these messages correspond to adapted data flow. +---------------+ +-------+ | OPES | == (original data flow) ==> |callout| Rousskov Expires April 26, 2004 [Page 7] Internet-Draft OPES Callout Protocol Core October 2003 | processor | <== (adapted data flow) === |server | +---------------+ +-------+ Figure 2 Depending on the negotiated application message definition, it may be possible or even required for callout server to respond with more than one application message within the same transaction. In other words, the callout server may adapt a single original application message into multiple application messages. Each application message sent by the callout server is individually identified by an "am-id" parameter (Section 11.6) and can be sent independently from other application messages within the same transaction (this allows for logical- and transport-level interleaving of OCP messages related to different application messages). The OPES processor receives the application message sent by the callout server. Other OPES processor actions specific to the application message received are out of this specification scope. 2.4 Termination Either OCP agent can terminate application message delivery, transaction, or connection by sending an appropriate OCP message. Usually, the callout server terminates application message delivery and the transaction. Abnormal terminations at arbitrary times are supported. The termination message includes a result description. 2.5 Exchange Patterns In addition to messages carrying application data, OCP agents may also exchange messages related to their configuration, state, transport connections, application connections, etc. A callout server may remove itself from the application message processing loop. A single OPES processor can communicate with many callout servers and vice versa. Though many OCP exchange patterns do not follow a classic client-server model, it is possible to think of an OPES processor as an ``OCP client'' and of a callout server as an ``OCP server''. The OPES architecture document [I-D.ietf-opes-architecture] describes configuration possibilities. The following informal rules illustrate relationships between transport connections, transactions, OCP messages, and application messages: o An OCP agent may communicate with multiple OCP agents. Communication with multiple OCP agents is outside of this specification scope. Rousskov Expires April 26, 2004 [Page 8] Internet-Draft OPES Callout Protocol Core October 2003 o An OPES processor may have multiple concurrent OCP connections to a callout server. Communication over multiple OCP connections is outside of this specification scope. o A connection may carry multiple concurrent transactions. A transaction is always associated with a single connection (i.e., a transaction cannot span multiple concurrent connections). o A connection may carry at most one message at a time, including control messages and transaction-related messages. A message is always associated with a single connection (i.e., a message cannot span multiple concurrent connections). o A transaction is a sequence of messages related to application of a given set of callout services to a single application message. A sequence of transaction messages from an OPES processor to a callout server is called original flow. A sequence of transaction messages from a callout server to an OPES processor is called adapted flow. The two flows may overlap in time. o A transaction is always associated with a single (original) application message. Adapted flow may transfer information about multiple (adapted) application messages. o An application message (adapted or original) is transferred using a sequence of OCP messages. 2.6 OCP Environment OCP communication is assumed to usually take place over TCP/IP connections on the Internet (though no default TCP port is assigned to OCP). This does not preclude OCP from being implemented on top of any other transport protocol, on any other network. OCP only presumes a reliable connection-oriented transport; any protocol that provides such guarantees can be used; the mapping of OCP message structures onto the transport data units of the protocol in question is outside the scope of this specification. OCP is application agnostic but it is not suitable for all applications. This specification documents known application scope limitations in Section 13. OCP messages can carry application-specific information as payload or application-specific message parameters. Rousskov Expires April 26, 2004 [Page 9] Internet-Draft OPES Callout Protocol Core October 2003 3. Messages As defined in Section 1.2, an OCP message is a basic unit of communication between an OPES processor and a callout server. A message is a sequence of octets formatted according to syntax rules (Section 3.1). Message semantics is defined in Section 12. Messages are transmitted on top of OCP transport. OCP messages deal with transport and transaction management as well as application data exchange between a single OPES processor and a single callout server. Some messages can only be emitted by an OPES processor; some only by a callout server; some can be emitted by both OPES processor and callout server. Some messages require responses (one could call such messages "requests"); some can only be used in response to other messages ("responses"); some may be sent without solicitation and/or may not require a response. 3.1 Message Format An OCP message consists of a message name followed by optional parameters and payload. The exact message syntax is defined by the following Augmented Backus-Naur Form (ABNF) [RFC2234]: message = name [SP anonym-parameters] [CRLF named-parameters CRLF] [CRLF payload CRLF] ";" CRLF anonym-parameters = value *(SP value) ; space-separated named-parameters = named-value *(CRLF named-value) ; CRLF-separated list-items = value *("," value) ; comma-separated payload = data named-value = name ":" SP value value = structure / list / atom structure = "{" [anonym-parameters] [CRLF named-parameters CRLF] "}" list = "(" [ list-items ] ")" atom = bare-value / quoted-value name = ALPHA *safe-OCTET bare-value = 1*safe-OCTET quoted-value = DQUOTE data DQUOTE data = size ":" OCTET ; n == size safe-OCTET = ALPHA / DIGIT / "-" / "_" size = dec-number ; 0-2147483647 Rousskov Expires April 26, 2004 [Page 10] Internet-Draft OPES Callout Protocol Core October 2003 dec-number = 1*DIGIT ; no leading zeros or signs Figure 3 Several normative rules accompany the above ABNF: o There is no "implied linear space" (LWS) rule. LWS rules are common to MIME-based grammars, but are not used here. The whitespace syntax is restricted to what is explicitly allowed by the above ABNF. o All protocol elements are case sensitive unless specified otherwise. In particular, message names and parameter names are case sensitive. o Sizes are interpreted as decimal values and cannot have leading zeros. o Sizes do not exceed 2147483647. o The size attribute in a quoted-value encoding specifies the exact number of OCTETs following the column (':') separator. If size OCTETs are not followed by a quote ('"') character, the encoding is syntactically invalid. o Empty quoted-values are encoded as a 4-OCTET sequence "0:". o Any bare-value MAY be encoded as a quoted-value. A quoted-value MUST be interpreted after the encoding is removed. For example, number 1234 can be encoded as four OCTETs 1234 or as eight OCTETs "4:1234", yielding exactly the same meaning. o By default, all values MUST be interpreted as having UTF-8 encoding. Note that ASCII is a UTF-8 subset, and that the syntax prohibits non-ASCII characters outside of the "data" element. (XXX: check that this is enough to satisfy i18n and whatever internationalization requirements IETF has) Messages violating formatting rules are, by definition, invalid. See Section 5 for rules on processing invalid messages. 3.2 Message Rendering OCP message samples in this specification and its application bindings may not be typeset to depict minor syntactical details of OCP message format. Specifically, SP and CRLF characters are not shown explicitly. No rendering of an OCP message can be used to infer Rousskov Expires April 26, 2004 [Page 11] Internet-Draft OPES Callout Protocol Core October 2003 message format. The message format definition above is the only normative source for all implementations. On occasion, an OCP message line exceeds text width allowed by this specification format. A backslash ("\"), a "soft linebreak" character is used to emphasize a protocol-violating presentation-only linebreak. Bare backslashes are prohibited by OCP syntax. Similarly, a "\r\n" string is sometimes used to emphasize the presence of a CRLF sequence, usually before OCP message payload. Normally, visible end of line corresponds to the CRLF sequence on the wire. The next section (Section 3.3) contains specific OCP message examples, some of which illustrate the above rendering techniques. 3.3 Message Examples OCP syntax provides for compact representation of short control messages and required parameters while allowing for parameter extensions. Below are examples of short control messages. The required CRLF sequence at the end of each line is not shown explicitly (see Section 3.2). TS 1; ping 123 2; data-pause 22 1; x-doit "5:xyzzy"; Figure 4 The above examples contain atomic anonymous parameter values such as number and string constants. OCP messages sometimes use more complicated parameters such as item lists or structures with named values. As both messages below illustrate, structures and lists can be nested: i-can ({"28:http://iana.org/opes/ocp/TLS"}); i-can ({\ "38:http://iana.org/opes/ocp/HTTP/response" Optional-Parts: (request-header) },{\ "38:http://iana.org/opes/ocp/HTTP/response" Optional-Parts: (request-header,request-body) Transfer-Encodings: (chunked) }); Figure 5 Optional parameters and extensions are possible using named Rousskov Expires April 26, 2004 [Page 12] Internet-Draft OPES Callout Protocol Core October 2003 parameters approach as illustrated by the following example. The data-need (Section 12.16) message in the example has three anonymous parameters and two named parameters (the last one being an extension). data-need 1 3 12345 size-request: 16384 x-need-info: "26:twenty six octet extension"; Figure 6 Finally, any message may have a payload part. For example, the Data Use Mine (DUM (Section 12.9)) message below carries 8865 bytes of raw data. DUM 1 3 0 8865 modp: 75 \r\n 8865:<... 8865 octets of raw data ...>; Figure 7 3.4 Message Names Most OCP messages defined in this specification have short names, formed by abbreviating or compressing a longer but human-friendlier message title. Short names without a central registration system (like this specification or IANA registry) are likely to cause conflicts. Informal protocol extensions should avoid short names. To emphasize what is already defined by message syntax, implementations cannot assume that all message names are very short. Rousskov Expires April 26, 2004 [Page 13] Internet-Draft OPES Callout Protocol Core October 2003 4. Transactions OCP transaction is a logical sequence of OCP messages processing a single original application message. The result of the processing may be zero or more application messages, adapted from the original. A typical transaction consists of two message flows: a flow from the OPES processor to the callout server (sending original application message) and a flow from the callout server to the OPES processor (sending adapted application messages). The number of application messages produced by the callout server and whether the callout server actually modifies original application message may depend on the requested callout service and other factors. The OPES processor or the callout server can terminate the transaction by sending a corresponding message to the other side. A OCP transaction starts with an explicit Transaction Start (TS (Section 12.5)) message sent by the OPES processor. A transaction ends with the first Transaction End (TE (Section 12.6)) message sent or received, explicit or implied, which can be sent by either side. Zero or more OCP messages associated with the transaction can be exchanged in between. The figure below illustrates possible message sequence (prefix "P" stands for OCP Client, OPES processor; prefix "S" stands for OCP callout server). Some message details are omitted. P: TS 10; P: AMS 10 1; ... processor sending application data to the callout server S: AMS 10 2; ... callout server sending application data to the processor ... processor sending application data to the callout server P: AME 10 1 result; S: AME 10 2 result; P: TE 10 result; Figure 8 Rousskov Expires April 26, 2004 [Page 14] Internet-Draft OPES Callout Protocol Core October 2003 5. Invalid input This specification contains many criteria for valid OCP messages and their parts, including syntax rules, semantics requirements, and relationship to agents state. "Invalid input" in this context means messages or message parts that violate at least one of the normative rules of this specification. A message with an invalid part is, by definition, invalid. Unless explicitly allowed otherwise, OCP agents MUST terminate the transaction if they receive an invalid message with transaction scope and MUST terminate the connection if they receive an invalid message with a connection scope. Such terminations MUST carry the result status code of 400 and MAY carry termination cause information in result status reason (see Section 11.10). OCP usually deals with optional but invasive application message manipulations where correctness ought to be valued above robustness. For example, a failure to insert or remove certain optional web page content is usually far less disturbing than corrupting the host page while performing that insertion or removal. Most OPES adaptations are high-level in nature, which makes it impossible to automatically assess correctness of operations, especially if "robustness guesses" are involved. Rousskov Expires April 26, 2004 [Page 15] Internet-Draft OPES Callout Protocol Core October 2003 6. Negotiation The negotiation mechanism allows OCP client and server to agree on mutually acceptable set of features, including optional and application-specific behavior as well as OCP extensions. For example, transport encryption, data format, and support for a new message can be negotiated. Negotiation implies intent for a behavioral change. A related mechanism allowing an agent to query capabilities of its counterpart without changing counterpart's behavior is described in Section 7. Most negotiations require at least one round trip time delay. In rare cases when other side's response is not required immediately, negotiation delay can be eliminated. Two core negotiation primitives are supported: negotiation offer and negotiation response. A Negotiation Offer (NO (Section 12.20)) message allows an agent to specify a set of features from which the responder has to select exactly one feature it prefers. The selection is sent using a Negotiation Response (NR (Section 12.21)) message. If the response is positive both sides assume that the selected feature is in effect. If the response is negative, no behavioral changes are assumed. In either case, further offers may follow. Negotiating OCP agents have to take into account prior negotiated (i.e., already enabled) features. OCP agents MUST NOT make and MUST reject offers that would lead to a conflict with already negotiated features. For example, an agent cannot offer an HTTP application profile for a connection that already has SMTP application profile enabled because there would be no way to resolve the conflict for a given transaction. Similarly, once TLSv1 connection encryption is negotiated, an agent must not offer and must reject offers for SSLv2 connection encryption. Negotiation Offer (NO (Section 12.20)) messages may be sent by either agent. Feature specifications MAY restrict initiator role to one of the agents. For example, negotiation of transport security feature [XXX] is initiated exclusively by OPES processors to avoid situations where both agents wait for each other to make an offer. Since either agent may make an offer, two "concurrent" offers may be made at the same time, by the two communicating agents. Unmanaged concurrent offers may lead to a negotiation deadlock. By giving OPES processor a priority, offer handling rules (Section 12.20) ensure that only one offer per transport connection is honored at a time, and the other concurrent offers are ignored by both agents. Violation of negotiation rules leads to OCP connection termination. Rousskov Expires April 26, 2004 [Page 16] Internet-Draft OPES Callout Protocol Core October 2003 This design reduces the number of negotiation scenarios resulting in a deadlock when one of the agents is not compliant. (XXX: add examples) Rousskov Expires April 26, 2004 [Page 17] Internet-Draft OPES Callout Protocol Core October 2003 7. Capability and State Inquiry This section describes OCP interface for querying the capability or state of an agent. A related mechanism allowing agents to negotiate features is described in Section 6. OCP supports two inquiry primitives: capability inquiry and state inquiry. Capability inquiry (see Section 12.23) is concerned about supported, but not necessarily active, features. A response to such a query (see Section 12.22) may contain ranges of supported feature parameters. State inquiry (Section 12.25) focuses on the current state of enabled and active features. A response to a state inquiry (Section 12.24) contains feature parameters specific to agent's current state at the time the inquiry is received. For example, a capability inquiry may reveal that an agent supports two transport security mechanisms while a state inquiry may show a specific security profile being enabled at the time of the inquiry. The primary purpose of these inquiries is debugging and troubleshooting rather than automated fine-tuning of cooperating agent behavior and configurations. The latter is directly supported by OCP negotiation mechanism. (XXX: do we need this OPTIONS-like feature at all?) (XXX: add examples) Rousskov Expires April 26, 2004 [Page 18] Internet-Draft OPES Callout Protocol Core October 2003 8. 'Data Recycling' Optimization Many adaptations do not require any data modifications (e.g., message logging or blocking). Some adaptations modify only a small portion of application message content (e.g., ad filtering or insertion). Yet, in many cases the callout service needs to see complete data. By default, unmodified data would first travel from the OPES processor to the callout server and then back. The "data recycling" optimization in OCP helps to eliminate the return trip if both OCP agents cooperate. This optimization is optional. To avoid sending unmodified data back, a callout service has to know that the OPES processor has a copy of the data. Since data sizes can be very large and the callout service may not know in advance whether it will be able to utilize the processor copy, it is not possible to require the processor to keep a copy of the entire original data. Instead, it is expected that a processor may keep some portion of the data, depending on processor settings and state. When processor commits to keeping a data chunk, it announces its decision and the chunk parameters via a Kept parameter of a Data Use Mine (DUM (Section 12.9)) message. The callout server MAY "use" the chunk by sending a Data Use Yours (DUY (Section 12.10)) message referring to the preserved chunk. That OCP message does not have payload and, hence, the return trip is eliminated. Since the mapping between original and adapted data is not known to the processor, the processor MUST keep the chunk until the end of the corresponding transaction, unless the callout server explicitly tells processor that the chunk is not needed. As implied by the above requirement, the processor cannot assume that a data chunk is no longer needed just because the callout server sent a Data Use Yours (DUY (Section 12.10)) message or adapted data with, say, the same offset as the preserved chunk. Both agents may benefit from data reuse. An OPES processor has to allocate storage to support this optimization while a callout server does not. On the other hand, it is the callout server that is responsible for relieving the processor from data preservation commitments. There is no simple way to resolve this conflict of interest on a protocol level. Some OPES processors may allocate a relatively small buffer for data preservation purposes and start discarding data when the buffer gets full. Such technique would benefit callout services that can quickly decide whether they need the data. Another processor strategy would be to size the buffer based on historical data reuse statistics. To improve chances of beneficial cooperation, callout servers are strongly encouraged to immediately notify OPES processors of unwanted data. The callout Rousskov Expires April 26, 2004 [Page 19] Internet-Draft OPES Callout Protocol Core October 2003 server that is not going to send a Data Use Yours (DUY (Section 12.10)) messages (for a specific data ranges or at all), SHOULD immediately inform the OPES processor of that fact with corresponding Data Won't Send Yours (DWSY (Section 12.11)) message(s) or other mechanisms. Rousskov Expires April 26, 2004 [Page 20] Internet-Draft OPES Callout Protocol Core October 2003 9. 'Out Of The Loop' Optimization Many services are applicable to a small percentage of application messages and yet have to see the beginning of every application message to decide on applicability (e.g., services that adapt based on declared or guessed MIME type). Many services adapt application message "headers" or "prefix" only and are not interested in the remaining parts of an application message (e.g., URL blocking and ad insertion services). 'Getting Out Of The Loop' optimization allows a callout server to get out of application message processing loop when the server is confident that it does not need to see remaining data. Two conditions are necessary for the callout server to get out of the loop nicely: No adaptation need: The callout server must finish its primary work. It should sent all adapted data to the processor and should require no more original data from the processor. Since adaptations and adaptation needs might not depend on original data, only the server can evaluate this condition. No copying need: The OPES processor must receive back all unpreserved data chunks that were sent to the callout server for adaptation. Note that data chunks that are not preserved and are not returned by the callout service would be lost. Since the server may not have seen all the original data sent, only the processor can evaluate this condition. Since no single agent can determine both conditions, the agents have to cooperate. The callout server has to tell the processor when the first condition is true. This is done via a Data Want Out (DWO (Section 12.13)) message (XXX: mention that it is not a "I Wont Adopt Anymore" message). The processor has to tell the service that there are no pending unpreserved data chunks. This is done by terminating the application message delivery using an Application Message End (AME (Section 12.8)) message with a 206 "Get Out" result. Between the above two conditions or messages, the callout server returns all original data unmodified back to the OPES processor, draining pending (uncopied) data queue (if any). Rousskov Expires April 26, 2004 [Page 21] Internet-Draft OPES Callout Protocol Core October 2003 10. Message Parameters This section defines parameter value types that are used for message definitions (Section 12). 10.1 Type Declaration Mnemonic A parameter value type is a named set of syntax and semantics rules. This section defines a simple, formal declaration mnemonic for types, labeled TDM. TDM is meant to facilitate type declaration in this specification and its extensions. OCP extensions MUST use TDM when declaring new value types. Atom, list, and structure constructs are three available base types. Their syntax and semantics rules are defined in Section 3.1. New types can be declared using TDM to extend base types semantics but not syntax. The following templates are used to extend semantics of types. The new semantics rules are meant to be attached to each declaration using prose text. Things in angle brackets are template placeholders to be substituted with actual type names or parameter name tokens; square brackets surround optional structure members. Declaring a new atomic type : extends atom; Declaring a new list with old-type-name items. Unless explicitly noted otherwise, empty lists are valid. : extends list of ; Declaring a new structure with a few anonymous members and named members. Neither group have to exist. Note that it is always possible for extensions to add more members to old structures without affecting type semantics because unrecognized members are ignored by compliant implementations. : extends structure with { [] ...; : ; : ; [: ]; ... }; Rousskov Expires April 26, 2004 [Page 22] Internet-Draft OPES Callout Protocol Core October 2003 Extending a non-base type with more semantics details. The "with {...}" part can only be used when old-type-name is a structure-based type; in this case, new anonymous members are appended to the anonymous members of the old structure, and new named members are merged with named members of the old structure. : extends with { [] ...; : ; : ; [: ]; ... }; All extended types may be used as a replacement of the types they extend. For example, a Negotiation Offer (NO (Section 12.20)) message defined below uses a parameter of type Features. Features, also defined below, is a list of Feature items. A Feature is a structure-based type. An OCP extension (e.g., an HTTP application binding) may extend the Feature type and use a value of that extended type in a negotiation offer. Recipients that are aware of the extension will recognize added members in Services items and negotiate accordingly. Others will ignore them. Declaring a parameter type freezes that parameter base syntax, but allows for fine-tuning its semantics in extensions. All OCP Core parameter types are declared using TDM. See below for examples. 10.2 Parameter Types This sections defines common parameter types using TDM. Before using a parameter value, an agent MUST check whether it has the expected type (i.e., whether it meets each rule from the type definition). A rule violation means that the parameter is invalid. See Section 5 for rules on processing invalid input. OCP extensions MAY define their own types. If they do, OCP extensions MUST define types with exactly one base format, and MUST specify type of every new parameter they introduce. 10.2.1 Uri uri: extends atom; Uri (universal resource identifier) is an atom formatted according to URI rules in [RFC2396]. Often, a uri parameter is used as a unique (within a given scope) identifier. Many uri parameters are URLs. Unless noted otherwise, URL Rousskov Expires April 26, 2004 [Page 23] Internet-Draft OPES Callout Protocol Core October 2003 identifiers do not imply existence of a serviceable resource at the location they specify. For example, an HTTP request for "http:// ietf.org/opes/ocp/raw/tcp" URL (XXX: identifying an OCP transport profile) may result in a 404 (Not Found) response. 10.2.2 Uni uni: extends atom; Uni (universal numeric identifier) is an atom formatted as dec-number and with a value in the [0, 2147483647] inclusive range. Often, a uni parameter is used as a unique (within a given scope) identifier. 10.2.3 Size size: extends atom; Size is an atom formatted as dec-number and with a value in the [0, 2147483647] inclusive range. OCP cannot handle application messages that exceed 2147483647 OCTETs in size or require larger sizes as a part of OCP marshaling process. However, since the definition of an application message is up to OCP agents, it is possible to work around this limitation at a processing level above OCP. 10.2.4 Boolean boolean: extends atom; Boolean type is an atom formatted as dec-number and with a value in the [0, 1] inclusive range. A value of zero ("0") is interpreted as "false". A value of one ("1") is interpreted as "true". Rousskov Expires April 26, 2004 [Page 24] Internet-Draft OPES Callout Protocol Core October 2003 11. Parameter Definitions 11.1 xid xid: extends uni; "Xid", an OCP transaction identifier, has "uni" type. "Xid" uniquely identifies an OCP transaction originated by a given OPES processor. 11.2 rid xid: extends uni; "Rid", an OCP request identifier, has "uni" type. "Rid" uniquely identifies an OCP request message on a connection. Request identifiers are used to match certain requests and responses. 11.3 service service: extends structure with { uri; }; "Service" is an "{id}" structure, where the id member is an OPES service identifier of type "Uri". Services may have service-dependent parameters. A document defining the service identifier for use with OCP MUST also define service-dependent parameters as additional "service" structure members, if any. For example, a "service" value may look like this: {"28:http://ietf.org/opes/ocp/tls" "8:blowfish"} 11.4 services services: extends list of service; "Services" is a list of "service" values. Unless noted otherwise, the order of the values is the requested or actual service application order. This parameter MAY appear in any message from the callout server that has an "am-id" parameter. If this parameter appears in a message from the callout server that carries or refers to application data, its value indicates the services actually applied to that data. If this parameter appears in a message from the callout server that neither carries nor refers to application data, its value indicates the services that MAY be applied to that application message in the future. (XXX: say where it cannot appear?)(XXX: make it symmetric with processor) Rousskov Expires April 26, 2004 [Page 25] Internet-Draft OPES Callout Protocol Core October 2003 11.5 sg-id sg-id: extends uni; "Sg-id", a service group identifier, is of type "uni". "Sg-id" uniquely identifies a group of services on an OCP connection. 11.6 am-id am-id: extends uni; "Am-id", an application message identifier, is of type "uni". "Am-id" uniquely identifies an application message within an OCP transaction. 11.7 size-request size-request: extends size; "Size-request" is of type "Size". The sender uses "size-request" to specify the number of data or metadata OCTETs it desires to receive. 11.8 offset offset: extends size; "Offset" is of type "Size". "Offset" describes payload start position relative to the application message data or metadata. The offset of the first application byte has a value of zero. 11.9 modp offset: extends percent; Future data modification prediction in percents. A modp value of 0 (zero) means the sender predicts that there will be no data modifications. A value of 100 means the sender is predicts that there will be data modifications. The value excludes data in the current OCP message, if any. The prediction applies to a single application message. This parameter can be used with any OCP message that has am-id parameter. 11.10 result result: extends structure with { atom [string]; }; OCP processing result. Result is a structure with two documented members: a required Uni status code and an optional string containing informative textual information, not intended for automated processing. For example, { 200 "2:OK" } Rousskov Expires April 26, 2004 [Page 26] Internet-Draft OPES Callout Protocol Core October 2003 This specification defines the following status codes: Result Status Codes +--------+--------------+-------------------------------------------+ | code | text | semantics | +--------+--------------+-------------------------------------------+ | 200 | OK | Overall success. This specification does | | | | not contain any general actions for 200 | | | | status code recipients. | | | | | | 206 | partial data | Partial success. When sent by an OPES | | | | processor, the remaining original data is | | | | not going to be sent due to the callout | | | | server disinterest expressed via a Data | | | | Won't Look At Yours (DWLY) or a Data Want | | | | Out (DWO) message. When sent by a callout | | | | server, the remaining adapted application | | | | data is identical to the remaining | | | | original data flow and should come | | | | directly from the OPES processor that | | | | already committed to "Out Of The Loop" | | | | optimization by sending a corresponding | | | | AME message after receiving a Data Want | | | | Out (DWO) message. | | | | | | 400 | failure | An error, exception, or trouble. A | | | | recipient of a 400 (failure) result of a | | | | AME, TE, or CE message MUST destroy any | | | | state or data associated with the | | | | corresponding data flow, transaction, or | | | | connection. For example, adapted version | | | | of the application message data must be | | | | purged from the processor cache if the | | | | OPES processor receives an Application | | | | Message End (AME) message with result | | | | code of 400. | +--------+--------------+-------------------------------------------+ Specific OCP messages may require code-specific actions. Extending result semantics is possible by adding new "result" structure members or negotiating additional result codes (e.g., as a part of a negotiated profile). A recipient of an unknown (in then-current context) result code MUST act as if code 400 (failure) was received. The recipient of a message without the actual result parameter, but Rousskov Expires April 26, 2004 [Page 27] Internet-Draft OPES Callout Protocol Core October 2003 with an optional formal result parameter MUST act as if code 200 (OK) was received. 11.11 feature feature: extends structure with { uri; }; A OCP feature identifier with optional feature parameters (sometimes called attributes). Used to declare support and negotiate use of OCP optional or extension features. OCP Core does not defines any features. Rousskov Expires April 26, 2004 [Page 28] Internet-Draft OPES Callout Protocol Core October 2003 12. Message Definitions This section describes specific OCP messages. Each message is given a unique name and usually has a set of anonymous and/or named parameters. The order of anonymous parameters is specified in the message definitions below. No particular order for named parameters is implied by this specification. No more than one named-parameter with a given name can appear in the message; messages with multiple equally-named parameters are semantically invalid. A recipient MUST be able to parse any valid message (see Section 3.1), subject to recipient resources limitations. If resources are exhausted or if a syntactically malformed message is received, the recipient MUST treat the message as invalid and having OCP connection scope (see Section 5). The recipient MAY distinguish resource limitations from syntax errors in the result reason string. Unknown or unexpected message names, parameters, and payloads may be valid extensions. For example, an "extra" anonymous parameter may be used for a given message, in addition to what is documented in the message definition below. A recipient MUST ignore any valid but unknown or unexpected name, parameter, member, or payload. Recipients MAY report (e.g., log) unknown or unexpected elements, of course. Some message parameter values are identifiers. These identifiers are created, used, and destroyed by OCP agents via corresponding messages. Except for messages that introduce new identifiers, all sent identifiers MUST be known to the recipient (i.e., introduced and not ended by previous messages). Except for messages that introduce new identifier value, unknown identifiers invalidate the host OCP message. The recipient of an unknown identifier value MUST treat the message as invalid. For example, recipient must terminate a transaction when Data Use Mine (DUM (Section 12.9)) message xid parameter refers to an unknown transaction. (XXX Message parameters in [square brackets] are OPTIONAL. Other parameters are REQUIRED.) 12.1 Connection Start (CS) name: CS anonymous parameters: none named parameters: none Rousskov Expires April 26, 2004 [Page 29] Internet-Draft OPES Callout Protocol Core October 2003 payload: no senders: OPES processor only A Connection Start (CS) message indicates the start of an OCP communication from the OPES processor. An OPES processor MUST send this message immediately after establishing a transport connection to the callout server. If the first message a callout server receives is not Connection Start (CS), the callout server MUST terminate the connection with a Connection End (CE (Section 12.2)) message. Upon receiving of this message, the callout server MUST either start maintaining connection state or refuse further processing by responding with a Connection End (CE (Section 12.2)) message. A callout server MUST maintain the state until it detects the end of the connection or until it terminates the connection itself. A callout server MUST NOT send this message (XXX: why?). If the first message received by an OPES processor is a Connection Start (CS (Section 12.1)) message, the processor MUST terminate the connection with a Connection End (CE (Section 12.2)) message. An OPES processor MUST NOT resend this message. If a callout server receives this message and it is not the first message on a connection, then, the callout server MUST terminate the connection with a Connection End (CE (Section 12.2)) message. With TCP/IP as transport, raw TCP connections (local and remote peer addresses) identify an OCP connection. Other transports may provide OCP connection identifiers to distinguish connections that share the same transport. For example, a single BEEP [RFC3080] channel may be designated as a single OCP connection. 12.2 Connection End (CE) name: CE anonymous parameters: [result] named parameters: [error] payload: no senders: both OPES processor and callout server Connection End (CE) Indicates an end of a transport connection. The agent initiating closing or termination of a connection MUST send this message immediately prior to closing or termination. The Rousskov Expires April 26, 2004 [Page 30] Internet-Draft OPES Callout Protocol Core October 2003 recipient MUST free associated state, including transport state. The destruction of the state ensures that messages outside of the old connection are ignored. Connection termination without a Connection End (CE) message indicates that the connection was prematurely closed without the closing-side agent prior knowledge or intent. When an agent detects a prematurely closed connection, the agent MUST behave as if a Connection End (CE) message indicating a fatal error was received. A Connection End (CE) message implies the end of all transactions, negotiations, and service groups opened or active on the connection being ended. 12.3 Create Service Group (SGC) name: SGC anonymous parameters: sg-id services named parameters: none payload: no senders: both OPES processor and callout server An Create Service Group (SGC) message instructs the recipient to associate a list of services with a given service group identifier ("sg-id"). The group can then be referred by the sender using the identifier. The recipient MUST maintain the association until a corresponding Destroy Service Group (SGD (Section 12.4)) message is received or implied. Service groups have a connection scope. Transaction management messages do not affect existing service groups. Maintaining service group associations requires resources (e.g., storage to keep the group identifier and a list of service IDs). Thus, there is a finite number of associations an implementation can maintain. Callout servers MUST be able to maintain at least one association for each OCP connection they accept. If a recipient of a Create Service Group (SGC) message does not create the requested association, it MUST immediately terminate the connection with a Connection End (CE (Section 12.2)) message. (XXX: document that wrong sq-id lead to semantically invalid messages) Rousskov Expires April 26, 2004 [Page 31] Internet-Draft OPES Callout Protocol Core October 2003 12.4 Destroy Service Group (SGD) name: SGD anonymous parameters: sg-id named parameters: none payload: no senders: both OPES processor and callout server A Destroy Service Group (SGD) message instructs the recipient to forget about the service group associated with the specified "sg-id" identifier. If "sg-id" refers to an existing group, the recipient MUST destroy the association. Otherwise, the recipient MUST treat the message as invalid. 12.5 Transaction Start (TS) name: TS anonymous parameters: xid sg-id named parameters: none payload: no senders: OPES processor only Indicates the start of an OCP transaction. A callout server MUST NOT send this message. Upon receiving of this message, the callout server MUST either start maintaining transaction state or refuse further processing by responding with a 'xaction-end' message. A callout server MUST maintain the state until it receives a message indicating the end of the transaction or until it terminates the transaction itself. The "sg-id" parameter refers to a service group created with a Create Service Group (SGC (Section 12.3)) message. If no group is associated with "sg-id", the callout server MUST treat the message as invalid. Otherwise, the callout server MUST use the list of services associated with "sg-id". This message introduces transaction identifier (xid). Rousskov Expires April 26, 2004 [Page 32] Internet-Draft OPES Callout Protocol Core October 2003 12.6 Transaction End (TE) name: TE anonymous parameters: xid, result named parameters: [error] payload: no senders: both OPES processor and callout server Indicates the end of the OCP transaction. The recipient MUST free associated state. The destruction of the state ensures that future messages referring to the same transaction, if any, will be ignored. This message terminates the life of the transaction identifier (xid). An OCP agent MUST send a Transaction End (TE) message immediately after it makes a decision to send no more messages related to the corresponding transaction. Violating this requirement may cause, for example, unnecessary delays and even timeouts for OPES processors that rely on this end-of-file condition to proceed. 12.7 Application Message Start (AMS) name: AMS anonymous parameters: xid, am-id named parameters: none payload: no senders: both OPES processor and callout server Indicates the start of processing of an application message. The recipient MUST either start processing the application message (and maintain its state) or refuse further processing with an 'app-message-end' message. The recipient MUST maintain the state until it receives a message indicating the end of application message processing or until it terminates the processing itself. When 'app-message-start' message is sent to the callout server, the callout server usually sends an app-message-start message back, announcing the creation of an adapted version of the original application message. Such response may be delayed. For example, the callout server may wait for more information to come from the OPES Rousskov Expires April 26, 2004 [Page 33] Internet-Draft OPES Callout Protocol Core October 2003 processor. When 'app-message-start' message is sent to the OPES processor, an OPTIONAL "services" parameter describes callout services that the server MAY apply to the application message. Usually, the "services" value matches what was asked by the OPES processor. This message introduces application message identifier (am-id). 12.8 Application Message End (AME) name: AME anonymous parameters: xid, am-id, result named parameters: [error] payload: no senders: both OPES processor and callout server Informs the recipient that there will be no more data for the corresponding application message and indicates the end of application message processing. The recipient MUST free associated application message state. The destruction of the state ensures that future messages referring to the same application message, if any, will be ignored. An Application Message End (AME) message ends any data preservation commitments associated with the corresponding application message. This message terminates the life of the application message identifier (am-id). An OCP agent MUST send an Application Message End (AME) message immediately after it makes a decision to send no more data for the corresponding application message. Violating this requirement may cause, for example, unnecessary delays and even timeouts for callout servers that rely on this end-of-file condition to proceed. 12.9 Data Use Mine (DUM) name: DUM anonymous parameters: xid, am-id, offset Rousskov Expires April 26, 2004 [Page 34] Internet-Draft OPES Callout Protocol Core October 2003 named parameters: [As-is: am-id offset], [Kept: offset], [modp], [ack] payload: yes senders: both OPES processor and callout server This is the only OCP message that may carry application data. There MUST NOT be any gaps in data supplied by Data Use Mine (DUM) and Data Use Yours (DUY) messages (i.e., the offset of the next data message must be equal to the offset plus the payload size of the previous data message) (XXX: we do not need offset then; should we keep it as a validation mechanism?) (XXX: document what to do when this MUST is violated). Zero payload size is permitted and is useful for communicating predictions without sending data. When an OPES processor sends a "Kept" parameter, the processor MUST keep a copy of the attached data (the preservation commitment starts). The offset parameter specifies the offset of the first OCTET in the payload (XXX: relative to what? DUM messages may transmit metadata that is not kept). The first "Kept" offset sent is zero. The next "Kept" offset sent is the previous "Kept" offset sent plus the size of the previous "Kept" payload, modulo 2^32. Recipients of invalid "Kept" parameters, MUST either terminate the corresponding transaction or MUST not use any "Kept" parameter during the transaction, including those received before the invalid one. This requirement helps preserve data integrity when "Kept" optimization is used by the processor. An "as-is" parameter, sent only by the callout server, MUST specify a data fragment in the original data flow. The callout server informs the processor that the attached data is identical to an original data fragment the processor sent earlier. Identical means that all adapted OCTETs have the same numeric value as the corresponding original OCTETs. The "am-id" field MUST correspond to the original application message identifier for the same transaction. If the parameter does not specify any original data fragment, the parameter is invalid. Invalid "as-is" parameters MUST be ignored. The recipient of an "ack" parameter MUST respond with a 'data-ack' message. Note that OCP Core does not require these acknowledgments to successfully exchange data; they are supported for debugging and similar important applications outside of the Core scope. The Data Use Mine (DUM) message has no effect on data preservation commitment (Section 8). Rousskov Expires April 26, 2004 [Page 35] Internet-Draft OPES Callout Protocol Core October 2003 12.10 Data Use Yours (DUY) name: DUY anonymous parameters: xid, am-id, kept-offset, kept-size payload: no senders: callout server only Tells the OPES processor to use "kept-size" bytes of preserved data starting at "kept-offset" offset, as if that data came from the callout server in a Data Use Mine (DUM (Section 12.9)) message with payload size equal to the "kept-size" parameter. The identified data fragment MUST be under the preservation commitment. If the OPES processor receives a Data Use Yours (DUY) message for data not under preservation commitment, the message is invalid. If a Data Use Yours (DUY) message is invalid, the OPES processor MUST abort am-id message processing (XXX: document how processing should be aborted). A Data Use Yours (DUY) message has no effect on data preservation commitment (Section 8). 12.11 Data Won't Send Yours (DWSY) name: DWSY anonymous parameters: xid, am-id, offset payload: no senders: callout server only The Data Won't Send Yours (DWSY) message relieves OPES processor from preservation commitment for data at or below the given offset. After sending this message, the callout server MUST NOT send Data Use Yours (DUY) messages referring to data at or below the given offset. An OPES processor that preserves any data at or below the offset MAY stop preserving that data. An OPES processor that does not preserve data at or below the offset MAY NOT start preserving that data. A callout server MAY send DWSY offsets lower than or equal to the previously sent DWSY offsets. However, as the above rules imply, such offsets would have no effect if processor already acted on a previous DWSY message with an equal or higher offset. Informally, a processor may maintain a single "not useful for preservation" size Rousskov Expires April 26, 2004 [Page 36] Internet-Draft OPES Callout Protocol Core October 2003 per transaction and that size would never decrease. Note that the message may refer to portions of data that has not been used via the Data Use Yours message, indicating that callout server is not going to use some preserved data. For example, an offset value of 2147483647 indicates that the server is not going to send any more Data Use Yours (DUY) messages. See the Data Won't Look At Yours (DWLY (Section 12.12)) message description for requirements related to using both DWSY and DWLY messages within one transaction. 12.12 Data Won't Look At Yours (DWLY) name: DWLY anonymous parameters: xid, am-id, offset payload: no senders: callout server only The Data Won't Look At Yours (DWLY) message informs OPES processor that the callout server is going to ignore and discard original data starting with the specified offset. After sending this message, the callout server MUST NOT send Data Use Yours (DUY) messages referring to data at or above the given offset. An OPES processor that preserves any data at or above the offset MAY stop preserving that data. An OPES processor that does not preserve data at or above the offset MAY NOT start preserving that data. If the recipient of a DWLY message has sent all original data below the given offset, the processor SHOULD terminate the original application message delivery using a Application Message End (AME (Section 12.8)) message with a 206 result status code. A callout server MAY send DWLY offsets higher than or equal to the previously sent DWLY offsets. However, as the above rules imply, such offsets would have no effect if processor already acted on a previous DWLY message with an equal or lower offset. Informally, a processor may maintain a single "not useful for sending" offset per transaction and that offset would never increase. For example, an offset value of zero indicates that the server is going to ignore all original data and generate an adapted application message from scratch. The OPES processor should most likely not send any data to the callout server in this case. Rousskov Expires April 26, 2004 [Page 37] Internet-Draft OPES Callout Protocol Core October 2003 A callout server MUST NOT use both Data Won't Look At Yours (DWLY) and Data Won't Send Yours (DWSY) messages during the same transaction. Doing so may make OPES processor 206 (partial content) status code ambiguous. If an OPES processor receives both DWLY and DWSY messages during the same transaction, the processor MUST terminate the transaction with an error. 12.13 Data Want Out (DWO) name: DWO anonymous parameters: xid, am-id, offset payload: no senders: callout server only The Data Want Out (DWO) message informs OPES processor that the callout server wants to get out of the processing loop once the original data at or above the specified offset is received (see Section 9). The OPES processor MAY respond (not necessarily immediately) with an Application Message End (AME) message with 206 result status code. If the callout server receives that 206 status code response, the server MAY terminate adaptation by sending an Application Message End (AME) message with 206 result status code and getting out of the loop. While waiting for the 206 status code response, the callout server MAY continue original data modifications. The Data Want Out (DWO) message indicates desire to get out of the loop, not a commitment to stop data modifications and not a permission to stop forwarding unmodified data. A callout server MUST NOT use both Data Want Out (DWO) and Data Won't Look At Yours (DWLY) messages during the same transaction. Doing so may make OPES processor 206 (partial content) status code ambiguous. If an OPES processor receives both DWO and DWLY messages during the same transaction, the processor MUST terminate the transaction with an error. 12.14 Data Pause (data-pause) name: data-pause anonymous parameters: xid am-id Rousskov Expires April 26, 2004 [Page 38] Internet-Draft OPES Callout Protocol Core October 2003 named parameters: none payload: no senders: callout server only Sent by a callout server, the Data Pause (data-pause) message informs the OPES processor that it must stop sending data to the callout server until the callout server explicitly asks for more data using a Data Need (data-need (Section 12.16)) message. Upon receiving a data-pause message, the OPES processor SHOULD stop sending application message data to the callout server. If the OPES processor stops sending, it SHOULD send a corresponding Data Paused (data-paused (Section 12.15)) message to the callout server. Until the OPES processor receives the message, it may continue sending data to the callout server, of course. Thus, when the callout server sends this message, it MUST NOT mark the application message as "paused". (XXX: should we use MUST or MAY instead of SHOULDs above?) An OPES processor MUST NOT send this message. A callout server MUST ignore this message. 12.15 Data Paused (data-paused) name: data-paused anonymous parameters: xid, am-id named parameters: none payload: no senders: OPES processor only Sent by an OPES processor, the Data Paused (data-paused) message informs the callout server that there will be no more data for the specified application message until the callout server explicitly asks for data using a 'Data Need (data-need (Section 12.16))' message. After sending a data-paused message, the OPES processor MUST stop sending application message data to the callout server. At that time, there may be still unprocessed data in the callout server queue, of course. When the callout server receives the message, it MAY mark the application message as "paused". If the callout server receives data for a paused message (a violation of the above MUST), the callout server MAY abort application message processing. A callout server MUST NOT send this message. An OPES processor MUST ignore this message. Rousskov Expires April 26, 2004 [Page 39] Internet-Draft OPES Callout Protocol Core October 2003 12.16 Data Need (data-need) name: data-need anonymous parameters: xid am-id offset named parameters: [Size-request: size] payload: no senders: callout server only Informs the OPES processor that the callout server needs more application message data. The "offset" parameter indicates the amount of data already received. If a "Size-request" parameter is present, its value is the suggested data size, and it MAY be ignored by the OPES processor. An absent "Size-request" parameter implies "any size". The callout server MUST clear the "paused" state of the application message processing just before sending this message. The OPES processor MUST ignore a data-need message if the OPES processor already sent request data. An OPES processor MUST NOT send Data Need (data-need) messages (XXX: should we give an OPES processor the same abilities to pause/resume message processing that a callout server has?) 12.17 Data ACK (DACK) name: DACK anonymous parameters: xid, am-id, offset, size named parameters: [wont-forward] payload: no senders: callout server only Informs the OPES processor that the corresponding data chunk has been received by the callout server. An optional "wont-forward" flag terminates preservation commitment for the corresponding data, if any. The flag is defined for callout server 'data-ack' messages only. Rousskov Expires April 26, 2004 [Page 40] Internet-Draft OPES Callout Protocol Core October 2003 Responding with Data ACK (DACK) messages to Data Use Mine (DUM (Section 12.9)) messages with an "ack" flag is REQUIRED. Responding with DACK messages to DUM messages without an "ack" flag is OPTIONAL. Implementations SHOULD be able to support debugging mode where every DUM message is acked. (XXX: should we require responses for Data Use Yours messages as well?) A 'data-ack' response SHOULD be sent as soon as possible. If the callout server does not know immediately whether it will forward the data, it MUST respond without a "wont-forward" flag. If, at any time, the callout server decides that it will not forward the data, it SHOULD send a 'data-ack' message with a "wont-forward" flag. Thus, multiple 'data-ack' messages and unsolicited 'data-ack' messages are allowed. Sending of a DACK message means that a complete DUM message has been received, but does not imply that the data has been processed in any other way. The data acknowledgment mechanism has several purposes: to allow OPES processor to gauge the speed at which the callout server is receiving data (for optimization purposes); to send back "wont-forward" notifications; and to assist in debugging OCP communications. 12.18 I Am Here (pong) name: pong anonymous parameters: [xid [am-id]] named parameters: none payload: no senders: both OPES processor and callout server Parameterless form informs the recipient that the sender is still maintaining the OCP connection. If "xid" or "am-id" identifier(s) are used, the message informs the recipient that the sender is still processing the corresponding transaction or an application message. An 'i-am-here' message MAY be sent without solicitation. An 'i-am-here' message MUST be sent in response to an 'are-you-there' request. The response MUST have the same set of "xid" and "am-id" parameters if those identifiers are still valid. The response MUST NOT use invalid identifiers. Rousskov Expires April 26, 2004 [Page 41] Internet-Draft OPES Callout Protocol Core October 2003 12.19 Are You There? (ping) name: ping anonymous parameters: [xid [am-id]] named parameters: none payload: no senders: both OPES processor and callout server Solicits an immediate 'i-am-here' response. If the response does not use the same set of "xid" and "am-id" parameters, the recipient MAY assume that missing identifier(s) correspond to OCP transaction or application message that was not maintained at the time the response was generated. The recipient MUST handle an 'are-you-there' request even if transaction or application message identifiers are invalid from the recipient point of view. Normally, messages with invalid identifiers are ignored. 12.20 Negotiation Offer (NO) name: NO anonymous parameters: (list of features) named parameters: [SG: sg-id] payload: no senders: both OPES processor and callout server A Negotiation Offer (NO) message solicits a selection of a single "best" feature out of a supplied list, using a Negotiation Response (NR (Section 12.21)) message. The sender is expected to list preferred features first when possible. The recipient MAY ignore sender preferences. If the list of features is empty, the negotiation is bound to fail but remains valid. Both OPES processor and callout server are allowed to send Negotiation Offer (NO) messages. The rules in this section ensure that only one offer is honored if two offers are submitted concurrently. An agent MUST NOT send a Negotiation Offer (NO) message if it still expects a response to its previous offer on the same connection. Rousskov Expires April 26, 2004 [Page 42] Internet-Draft OPES Callout Protocol Core October 2003 If an OPES processor receives a Negotiation Offer (NO) message while its own offer is pending, the processor MUST disregard the server offer. Otherwise, it MUST respond immediately. If a callout server receives a Negotiation Offer (NO) message when its own offer is pending, the server MUST disregard its own offer. In either case, it MUST respond immediately. If an agent receives a message sequence that violates any of the above rules in this section, the agent MUST terminate the connection with an error. An optional "SG" parameter is used to narrow the scope of negotiations to the specified service group. If SG is present, the negotiated features are negotiated and enabled only for transactions that use the specified service group ID. Connection-scoped features are negotiated and enabled for all service groups. The presence of scope does not imply automatic conflict resolution common to programming languages; no conflicts are allowed. When negotiating connection-scoped features, an agent MUST check for conflicts within each existing service group. When negotiating group-scoped features, an agent MUST check for conflicts with connection-scoped features already negotiated. For example, it must not be possible to negotiate a connection-scoped HTTP application profile if one service group already has an SMTP application profile and vice versa. OCP agents SHOULD NOT send offers with service groups used by pending transactions. Unless explicitly noted otherwise in a feature documentation, OCP agents MUST NOT apply any negotiations to pending transactions. In other words, negotiated features take effect with the new OCP transaction. 12.21 Negotiation Response (NR) name: NR anonymous parameters: [feature] named parameters: [SG: sg-id], [Rejects], [Unknowns] payload: no senders: both OPES processor and callout server A Negotiation Response (NR) message conveys recipient reaction to a Negotiation Offer (NO (Section 12.20)) request. An accepted offer is indicated by the presence of a "feature" parameter, containing the selected feature. If the selected feature does not match any of the Rousskov Expires April 26, 2004 [Page 43] Internet-Draft OPES Callout Protocol Core October 2003 offered features, the offering agent MUST consider negotiation failed and MAY terminate the connection. A rejected offer is indicated by omitting the "feature" parameter. If negotiation offer contains an SG parameter, the responder MUST include that parameter in the Negotiation Response (NR) message. The recipient of a NR message without the expected SG parameter MUST treat negotiation response as invalid. If negotiation offer lack an SG parameter, the responder MUST NOT include that parameter in the Negotiation Response (NR) message. The recipient of a NR message with an unexpected SG parameter MUST treat negotiation response as invalid. When accepting or rejecting an offer, the sender of the Negotiation Response (NR) message MAY supply additional details via Rejects and Unknowns parameters. The Rejects parameter can be used to list features that were known to the Negotiation Offer (NO (Section 12.20)) recipient but could not be supported given negotiated state that existed when NO message was received. The Unknowns parameter can be used to list features that were unknown to the NO recipient. 12.22 I Support (i-can) name: i-can anonymous parameters: [feature] named parameters: none payload: no senders: both OPES processor and callout server An I Support (i-can) message is sent in response to a Can You Support (can-you (Section 12.23)) question. If the sender supports feature identifier, the sender MUST respond with a "feature" parameter, set to match actually supported feature and its attributes, if any. Otherwise, the sender MUST respond without a "feature" parameter. Note that supported features attributes of the sender may differ from those in the Can You Support (can-you (Section 12.23)) question, indicating a partial match or a mismatch. 12.23 Can You Support (can-you) Rousskov Expires April 26, 2004 [Page 44] Internet-Draft OPES Callout Protocol Core October 2003 name: can-you anonymous parameters: feature named parameters: none payload: no senders: both OPES processor and callout server Can You Support (can-you) message solicits a declaration of support for the supplied feature, using an I Support (i-can (Section 12.22)) message. The recipient MUST respond immediately. 12.24 I Currently Use (i-do) name: i-do anonymous parameters: feature named parameters: none payload: no senders: both OPES processor and callout server 12.25 Do You Currently Use (do-you) name: do-you anonymous parameters: feature named parameters: none payload: no senders: both OPES processor and callout server Rousskov Expires April 26, 2004 [Page 45] Internet-Draft OPES Callout Protocol Core October 2003 13. Application Protocol Requirements Not all application protocols can be adapted with OCP. Compiling a complete list of known limitations is impossible since "application protocol" is not a well defined term. However, listing known limitations can help it determining OCP applicability. This section is not a normative part of the OCP specification. Application protocol messages must have byte boundaries. OCP can only handle application messages with the number of bits divisible by 8. XXX Rousskov Expires April 26, 2004 [Page 46] Internet-Draft OPES Callout Protocol Core October 2003 14. IAB Considerations OPES treatment of IETF Internet Architecture Board (IAB) considerations [RFC3238] are documented in [XXX]. Rousskov Expires April 26, 2004 [Page 47] Internet-Draft OPES Callout Protocol Core October 2003 15. Security Considerations This section examines security considerations for OCP. OPES threats are documented in [XXX-Threat-Doc]. OCP relays application messages that may contain sensitive information. Appropriate transport encryption can be negotiated to prevent information leakage or modification (see section XXX on transport security profile negotiation), but OCP agents may support unencrypted transport by default. Such default OCP agent configurations will expose application messages to third party recording and modification, even if OPES agents themselves are secure. OCP implementation bugs may lead to security vulnerabilities in OCP agents, even if OCP traffic itself remains secure. For example, a buffer overflow in a callout server caused by a malicious OPES processor may grant that processor access to information from other (100% secure) OCP connections, including connections with other OPES processors. Careless OCP implementations may rely on various OCP identifiers to be unique across all OCP agents. A malicious agent can inject an OCP message that matches identifiers used by other agents, in an attempt to get access to sensitive data. OCP implementations must always check an identifier for being "local" to the corresponding connection before using that identifier. OCP is a stateful protocol. Several OCP commands increase the amount of state that the recipient has to maintain. For example, a Create Service Group (SGC (Section 12.3)) message instructs the recipient to maintain an association between a service group identifier and a list of services. Implementations that cannot handle resource exhaustion correctly increase security risks. The following are known OCP-related resources that may be exhausted during a compliant OCP message exchange: OCP message structures: OCP message syntax does not limit the nesting depth of OCP message structures and does not place an upper limit on the length (number of OCTETs) of most syntax elements. concurrent connections: OCP does not place an upper limit on the number of concurrent connections that a callout server may be instructed to create via Connection Start (CS (Section 12.1)) messages. Rousskov Expires April 26, 2004 [Page 48] Internet-Draft OPES Callout Protocol Core October 2003 service groups: OCP does not place an upper limit on the number of service group associations that a callout server may be instructed to create via Create Service Group (SGC (Section 12.3)) messages. concurrent transactions: OCP does not place an upper limit on the number of concurrent transactions that a callout server may be instructed to maintain via Transaction Start (TS (Section 12.5)) messages. concurrent flows: OCP Core does not place an upper limit on the number of concurrent adapted data flows that an OPES processor may be instructed to maintain via Application Message Start (AMS (Section 12.7)) messages. Denial of service attacks using OCP may slow a callout server down, affecting performance of many independent OPES processors and, hence, user-perceived performance. (XXX: this has nothing to do with OCP and should be deleted from these specs, right?) Rousskov Expires April 26, 2004 [Page 49] Internet-Draft OPES Callout Protocol Core October 2003 16. Compliance This specification defines compliance for the following subjects: OCP client implementations (OPES processors), OCP server implementations (callout servers), OCP application profiles, and OCP extensions. A subject is compliant if it satisfies all applicable "MUST" and "SHOULD" level requirements. By definition, to satisfy a "MUST" level requirement means to act as prescribed by the requirement; to satisfy a "SHOULD" level requirement means to either act as prescribed by the requirement or have a reason to act differently. A requirement is applicable to the subject if it instructs (addresses) the subject. Informally, OCP compliance means that there are no known "MUST" violations, and all "SHOULD" violations are conscious. In other words, a "SHOULD" means "MUST satisfy or MUST have a reason to violate". It is expected that compliance claims are accompanied by a list of unsupported SHOULDs (if any), in an appropriate format, explaining why preferred behavior was not chosen. Only normative parts of this specification affect compliance. Normative parts are: parts explicitly marked using the word "normative", definitions, and phrases containing unquoted capitalized keywords from [RFC2119]. Consequently, examples and illustrations are not normative. OCP extensions MAY change any normative requirement documented in this specification, including OCP message format, except for the following rule: Changes to normative parts of OCP Core MUST be negotiated. Rousskov Expires April 26, 2004 [Page 50] Internet-Draft OPES Callout Protocol Core October 2003 17. To-do L4+ binding: Mention that transport might be L4 or above timeouts: document what messages cause what timers to be [re]set. parameter scope: Document that parameter names have message scope. A known parameter name in an unknown message does not identify a known parameter. name named-paramters: Document names for all named parameters. modified: replace with as-is approach dack: Make data acknowledgment mechanism symmetric. Both agents should be able to request DACK messages. Should we make the acknowledgment mechanism to work with any OCP message? Merge with ping/pong mechanism? flags: Document flag parameter syntax ("0/1" or present/absent). loss: Should OPES processor be able to signal loss of data to the callout server. The current wording assumes that offset is incremented using sizes of actually received data fragments; if the processor detects loss it cannot pass that information and can only hope that the callout server will notice (by interpreting the data) or will not care (the server may be application- and/or loss-agnostic; e.g., a logging or billing server) modp: Min and max values (0 and 100) should be "commitments" rather than "probabilities". transactions-end: Decide whether we need a 'transactions-end' message to terminate multiple transactions efficiently. Is terminating a connection good enough? error: Do we need this flag or should we use result codes to relay the same meaning? abort negotiation: Should we let the other side affect the abort decision on OPES level? Perhaps the callout server is doing some logging or accounting and MUST see every byte received by the OPES processor, even if the application message is aborted by the processor. Should we add some kind of 'xaction-need-all' message? Or should we assume that the dispatcher always knows callout server needs and vice versa? Rousskov Expires April 26, 2004 [Page 51] Internet-Draft OPES Callout Protocol Core October 2003 proxying Can OCP be proxied above transport layer? Perhaps to implement parts of a given service, transparently to the OPES processor? normative IDs: To be normative, OPES Internet-Drafts must be replaced with corresponding RFCs when the latter are published. Rousskov Expires April 26, 2004 [Page 52] Internet-Draft OPES Callout Protocol Core October 2003 Appendix A. Acknowledgements The author gratefully acknowledges the contributions of: Abbie Barbir (Nortel Networks), Oskar Batuner (Independent Consultant), Karel Mittig (France Telecom R&D), Markus Hofmann (Bell Labs), Hilarie Orman (The Purple Streak), Reinaldo Penno (Nortel Networks), Martin Stecher (Webwasher) as well as an anonymous OPES working group participant. Special thanks to Marshall Rose for his xml2rfc tool. Rousskov Expires April 26, 2004 [Page 53] Internet-Draft OPES Callout Protocol Core October 2003 Appendix B. Change Log Internal WG revision control ID: $Id: ocp-core.xml,v 1.35 2003/10/27 11:40:33 rousskov Exp $ 2003/10/26 * Started using TDM for Core value types. * Added Data Want Out (DWO) message. * Added Data Wont Look at Yours (DWLY) message. * Renamed Wont-Use to more specific Wont-Send. Made Wont-Send parameter into a Data Wont Send Yours (DWSY) message because it controls original data flow and is not specific to a particular adapted AM (there can be many). This change means that Data Use Yours (DUY) messages are no longer terminating preservation commitment by default. Thus, we lost a little in terms of performance (unless processors look ahead for DWSYs) but gained a lot of simplicity in terms of support for multiple adapted application messages (SMTP case). * Added 206 (partial data) status code definition. * 206 status code should be used with AME, not TE. * Replaced "global scope" with "connection scope" in negotiation rules. 2003/10/25 * Clarified negotiation mechanism when it comes to negotiating multiple [possibly conflicting] features. * Clarified service group-scoped negotiations. Agents must watch out for global conflicts when doing group-scoped negotiations and vice-versa. 2003/10/24 * Added 'Out Of The Loop' Optimization section. * Added 'Data Recycling' Optimization section. * Added "Type Declaration Mnemonic" (TDM) to facilitate type declarations here and in OCP extensions. Rousskov Expires April 26, 2004 [Page 54] Internet-Draft OPES Callout Protocol Core October 2003 2003/10/19 * Removed optional "sizep" parameter. HTTP needs content-dependent parameter (AM-EL), and we do not know any generic application for sizep that would be worth supporting in Core. 2003/10/08 * Documented backslash (\) and CRLF (\r\n) OCP message rendering tricks. 2003/10/07 * Added named structure members to message BNF. Used MIME-like syntax already used for named parameters. Named members are needed to represent optional structure members. head-sid15 * Removed leftovers of data-have message name. Use Data Use Mine instead (Karel Mittig). * Anonymized named parameters and removed currently unused "rid" parameter in ping and pong messages (Karel Mittig). * Renamed DUM.please-ack to "DUM.ack" (Karel Mittig). More work is needed to polish and simplify acknowledgment mechanism. head-sid14 * Documented known resource-exhaustion security risks. * Polished compliance definition. Avoid two levels of compliance. head-sid13 * Added SG parameter to Negotiation Offer (NO) and Negotiation Response (NR) messages to limit the result of negotiations to the specified service group. Still need to document SG-related logic in the Negotiation section. * Removed "services" parameter from Transaction Start (TS) message because we have to rely on service groups exclusively, because only service groups can have negotiated application profiles associated with them. * Replaced data-id parameter with "Kept: kept-offset" and Rousskov Expires April 26, 2004 [Page 55] Internet-Draft OPES Callout Protocol Core October 2003 "Wont-Use: used-size" parameter. We probably need octet-based granularity, and old data-id only offered fragment-based granularity. * Made AME and TE messages required. * Documented result parameter syntax and two result codes: 200 (success) and 400 (failure). * Added optional "result" parameter to CE. head-sid12 * Fixed BNF to remove extra SP and "," in front of structure and list values. * Fixed the type of "id" field in a "service" structure. * Documented "sg-id" parameter. * Renamed "copied" to "data-id" so that it can be used by both agents. An OPES processor uses named "Copied: data-id" parameter and a callout server uses anonymous "data-id" parameter (instead of previously documented "copy-am-offset"). * Removed "rid" parameter from Negotiation Offer (NO) message as unused. * Removed "size" parameter from messages with payload since payload syntax includes an explicit size value. * Renamed Data Have (DH) message to Data Use Mine (DUM) message to preserve the symmetry with Data Use Yours (DUY) message and to prepare for possible addition of Data Check Mine (DCM) message. * Finished phasing out the "modified" message parameter. * Added an "As-is" named-parameter to mark adapted pieces of data identical to the original. * Replaced a huge "message nesting" figure with a set of short specific rules illustrating the same concept. Added a new "Exchange Patterns" subsection to accommodate the rules and related matters. The figure was not clear enough. Hopefully, the rules are. Rousskov Expires April 26, 2004 [Page 56] Internet-Draft OPES Callout Protocol Core October 2003 head-sid10 * Removed the concept of OCP connection as a group of messages sharing the same group of callout services. Now there is no difference between OCP connection and transport connection. * Added a concept of a Service Group, which is a list of services with an identifier, for now. A given Service Group is referenced by the creating/destroying side only, to prevent destruction synchronization. * Removed Connection Services (CSvc) message. * Removed connection priority until proven generally useful. Can be implemented as an extension. head-sid9 * Added Negotiation and Capability Inquiry sections. * Deleted data-end message because AME (Application Message End) already does the same thing and because there is no data-start message. * Deleted meta-* messages. Data-* messages are now used for both metadata and data since OCP does not know the difference, but must provide the same exchange mechanism for both. * Use a single message name (short or long, depending on the message) instead of using full and abbreviated versions and trying to enforce abbreviations on the wire. Be more consistent in creating short message names. * Resurrected OCP scope figure based on popular demand. * Applied Martin Stecher comments dated 2003/05/30. head-sid8 * Added structure and list values to ABNF syntax. * Messages with multiple equally-named parameters are semantically invalid. * Added types for message parameters. * Started replacing complicated, error-prone, and probably mostly useless "modified" parameter with a clear and simple "as-is" Rousskov Expires April 26, 2004 [Page 57] Internet-Draft OPES Callout Protocol Core October 2003 parameter. * Converted parameter descriptions from list items to subsections. * OCP syntax requires one or two character lookups to determine the next message part. Fixed a comment for implementors saying that one lookup is always sufficient. head-sid7 * Mentioned TCP/IP/Internet as assumed transport/network, with any other reliable connection-oriented transport/network usable as well. We do not document how OCP messages are mapped to TCP but it should be obvious. See Overall Operation section. * Applied Martin Stecher's corrections to OCP message syntax and definitions of messages. * Restricted full message name use to documentation, debuggers, and such. The differences in abbreviated and full name usage still need more consideration and polishing. * IAB Considerations section now refers to the future opes-iab draft. head-sid6 * Added OCP message syntax. Reformatted message descriptions to match new syntax concepts. * Started adding meta-have message to exchange metadata details. Removed negotiation messages for now (posted new messages to the list for a discussion). * Added Security Considerations section (based on Abbie Barbir's original text). head-sid4 * Changed document labels to reflect future "WG draft" status. * Added Acknowledgments section. * Added "Core" to the title since we expect application specific drafts to follow and because this document, even when complete, cannot specify a "working" protocol without application-specific parts. This change is still debatable. Rousskov Expires April 26, 2004 [Page 58] Internet-Draft OPES Callout Protocol Core October 2003 * Added reference to required future application-specific specs in the Introduction. * Moved all rant about irrelevance of application protocols proxied by an OPES processor to the "Application proxies and OCP scope" section. Removed "processor input" and "processor output" terms. No reason to define a new term when its only purpose is to document irrelevance? * Moved "OCP message" definition to the terminology section. * Clarified "application message" definition based on recent WG discussions and suggestions. There seems to be consensus that "application message" is whatever OPES processor and callout server define or agree on, but OCP needs some minimal structure (content + metadata) * Synced data and metadata definitions with the new "application message" definition. * Simplified "Overall Operation" section since it no longer need to talk about irrelevance of application protocols proxied by an OPES processor. * Illustrated nesting/relationship of key OCP concepts (application message, OCP message, transaction, connection, transport connection, etc.). The figure needs more work. * Listed all from-processor and from-server OCP messages in one place, with references to message definitions. * Added "services" message parameter, assuming that more than one service may be requested/executed with one transaction. * Gave callout server ability to report what services were actually applied (see "services" parameter definition). head-sid3 * clarified application message definition and OCP boundaries by introducing three kinds of "applications": processor input, processor output, and OCP application * made "Overall Operation" a top-level section since it got long and has its own subsections now; lots of editorial changes in this sections, new figures * added illustrations of OCP messages, transactions, and Rousskov Expires April 26, 2004 [Page 59] Internet-Draft OPES Callout Protocol Core October 2003 connections head-sid2 * introduced a notion of meta-data to both simplify OCP and make OCP agnostic to application meta-data; previous approach essentially assumed existence of a few common properties like protocol name or application message source/destination while not allowing any other properties to be exchanged between OCP agents); specific meta-data format/contents is not important to OCP but OCP will help agents to negotiate that format/contents * removed wording implying that OCP adapts application messages; OCP only used to exchange data and meta-data (which facilitates adaptation) * changed most of the definitions; added definitions for meta-data, original/adapted flows, and others * split 'data-pause' message into 'data-pause' request by the callout server and 'data-paused' notification by the OPES processor; fixed "paused" state management * added motivation for data acking mechanism * replaced "am-proto", "am-kind", "am-source", and "am-destination" parameters with "meta-data" * replaced SERVER and CLIENT placeholders with "callout server" and "OPES processor" * added editing marks Rousskov Expires April 26, 2004 [Page 60] Internet-Draft OPES Callout Protocol Core October 2003 Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997. [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1998. [I-D.ietf-opes-architecture] Barbir, A., "An Architecture for Open Pluggable Edge Services (OPES)", draft-ietf-opes-architecture-04 (work in progress), December 2002. Rousskov Expires April 26, 2004 [Page 61] Internet-Draft OPES Callout Protocol Core October 2003 Informative References [I-D.ietf-opes-protocol-reqs] Beck, A., "Requirements for OPES Callout Protocols", draft-ietf-opes-protocol-reqs-03 (work in progress), December 2002. [I-D.ietf-opes-scenarios] Barbir, A., "OPES Use Cases and Deployment Scenarios", draft-ietf-opes-scenarios-01 (work in progress), August 2002. [I-D.ietf-opes-http] Rousskov, A. and M. Stecher, "HTTP adaptation with OPES", draft-ietf-opes-http-00 (work in progress), August 2003. [I-D.ietf-fax-esmtp-conneg] Toyoda, K. and D. Crocker, "SMTP Service Extension for Fax Content Negotiation", draft-ietf-fax-esmtp-conneg-08 (work in progress), June 2003. [RFC2616] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. [RFC3080] Rose, M., "The Blocks Extensible Exchange Protocol Core", RFC 3080, March 2001. [RFC3238] Floyd, S. and L. Daigle, "IAB Architectural and Policy Considerations for Open Pluggable Edge Services", RFC 3238, January 2002. Author's Address Alex Rousskov The Measurement Factory EMail: rousskov@measurement-factory.com URI: http://www.measurement-factory.com/ Rousskov Expires April 26, 2004 [Page 62] Internet-Draft OPES Callout Protocol Core October 2003 Intellectual Property Statement The IETF takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on the IETF's procedures with respect to rights in standards-track and standards-related documentation can be found in BCP-11. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification can be obtained from the IETF Secretariat. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to practice this standard. Please address the information to the IETF Executive Director. Full Copyright Statement Copyright (C) The Internet Society (2003). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assignees. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION Rousskov Expires April 26, 2004 [Page 63] Internet-Draft OPES Callout Protocol Core October 2003 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society. Rousskov Expires April 26, 2004 [Page 64]