OPES Callout Protocol Core

The Open Pluggable Edge Services (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 and collaborating with one or more remote callout servers. As described in , 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, "OPES adaptation of HTTP" [XXX] describes, in part, how HTTP messages and HTTP meta-information can be communicated over OCP.

(XXX: a better section title would be nice) 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 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 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), 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.

The all-caps 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 . 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. (XXX: Some OCP elements are called "callout" elements in the OCP requirements document. We assume that OCP is equivalent to "callout" in this context. For example, OCP connection is the same as callout connection. Should we be more consistent?) 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. Message semantics is defined in . An entity defined by OPES processor and callout server negotiation. Usually, the negotiated definition would match the definition from an application protocol (e.g., definition of an HTTP message, including headers, body, and trailers). 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. Same as application message data. Referring to application message flowing from the OPES processor to a callout server. (XXX: we need a better term than "original") Referring to application message flowing from an OPES callout server to the OPES processor. 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. 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. Performing the specified action before processing new incoming messages or sending any new messages unrelated to the specified action.

(XXX: this section is to be removed from the final protocol specs) This specification is not fully suitable for writing OCP implementations as some behavioral and formatting aspects are not yet documented. They will be. Note that application-specific details are documented separately, as described in the "Introduction" section. contains a list of to-be-implemented items.

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. (XXX: is this paragraph needed? out of place?

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) messages. Next, OCP features can be negotiated between the processor and the callout server (see ). For example, OCP agents have to agree on transport encryption and application message definition. When negotiation is complete, OCP agents may start exchanging application messages.

When OPES processor wants to adapt an application message, the OPES processor sends a Transaction Start (TS) message to initiate an OCP transaction dedicated to that application message. Some transaction properties may need to be renegotiated at this time (XXX: undocumented and might not be needed). The processor then sends a Transaction Start (TS) 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 Have (DH) and related OCP message(s). All these messages correspond to original 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-have' OCP message(s). The application message is then announced to be "closed" using 'app-message-close' message. The transaction may be closed using 'xaction-end' message as well. All these messages correspond to adapted data flow.

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 "am-id" parameter 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.

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. Termination OCP message include a result description. 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. 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 describes configuration possibilities. The diagram below illustrates relationship between transport connections, transactions, OCP messages, and application messages. Not all possible scenarios are illustrated.

(XXX: the above figure is probably too big and too detailed; what parts should be left, moved, deleted? any better rendering ideas?) 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 . OCP messages can carry application specific information as payload or application-specific extension parameters.

As defined in , 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. Message semantics is defined in . 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.

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) :

Several rules accompany the above ABNF: 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. All protocol elements are case sensitive unless specified otherwise. In particular, message names and parameter names are case sensitive. Sizes are interpreted as decimal values and cannot have leading zeros. Sizes do not exceed 2147483647. 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. Empty quoted-values are encoded as a 4-OCTET sequence "0:". Any parameter 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. (XXX: this makes digital signatures more difficult, see todo) By default, all values MUST be interpreted as having UTF-8 encoding. Note that ASCII is a UTF-8 subset. Messages violating formatting rules are, by definition, invalid (see Section XXX for rules on processing invalid messages). Comment for implementors: OCP messages have three major parts: anonymous parameters, named parameters, and payload. One or two character lookups are sufficient to determine the next part. If the first character is a semicolumn (";"), all optional parts have been parsed. If the first lookup character is a space, anonymous parameters follow. If the first lookup character is CRLF then the second lookup is needed: if the second character is a digit, payload follows; otherwise, named parameters follow. Other syntax and semantics rules must still be obeyed, of course. For example, once a named parameter or payload has been discovered, no anonymous parameters should be accepted. Similarly, a single character lookup is sufficient to distinguish a bare value from a quoted one since only quoted values start with a quote character.

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. Required CRLF sequences at the end of messages are not shown explicitly.

Optional parameters and extensions are possible using named parameters approach as illustrated by the following example. The 'data-need' message in the example has three anonymous parameters and two named parameters (the last one being an extension). Required CRLF sequence at the end of each line is not shown explicitly.

Finally, any message may have a payload part. For example, the 'data-have' message below carries 8865 bytes of raw data. Required CRLF sequence at the end of each line is not shown explicitly.

; ]]>

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 must not assume that all message names are very short.

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 a explicit 'xaction-start' message sent by the OPES processor. A transaction ends with the first 'xaction-end' message, 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).

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 . 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. The Negotiation Offer (NO) 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) 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. Negotiation Offer (NO) 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, from the two communicating agents. Unmanaged concurrent offers may lead to a negotiation deadlock. By giving OPES processor a priority, offer handling rules 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. This design reduces the number of negotiation scenarios resulting in a deadlock when one of the agents is not compliant. (XXX: add examples)

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 . OCP supports two inquiry primitives: capability inquiry and state inquiry. Capability inquiry (see ) is concerned about supported, but not necessarily active, features. A response to such a query (see ) may contain ranges of supported feature parameters. State inquiry () focuses on the current state of enabled and active features. A response to a state inquiry () 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 now. 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)

This section defines parameters that are used for message definitions. For ease of reference, each parameter is given a unique name, even if it is used exclusively as an anonymous parameter.

This sections defines parameter types. In OCP context, a type is a named set of semantic rules attached to a known value syntax construct (e.g., atom, list, or structure). This specification documents expected types for each formal parameter. Before using a parameter value, an implementation MUST check whether it matches the expected type. A mismatch means that the message is invalid. Specifications based on OCP Core MAY define their own types and MUST declare types of every new formal parameter they introduce.

Uri (universal resource identifier) is an atom formatted according to URI rules in . Often, a uri parameter is used as a unique (within a given scope) identifier. Many uri parameters are URLs. Unless noted otherwise, URL 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.

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.

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.

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".

"Xid", an OCP transaction identifier, has "uni" type. "Xid" uniquely identifies an OCP transaction originated by a given OPES processor.

"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.

"Service" is an "{id}" structure, where the id member is an OPES service identifier of type "Uni". 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:

"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)

"Am-id", an application message identifier, is of type "uni". "Am-id" uniquely identifies an application message within an OCP transaction.

"Size-request" is of type "Size". The sender uses "size-request" to specify the number of data or metadata OCTETs it desires to receive.

"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.

(XXX: This parameter is not longer used and will be deleted. Old definition was not very practical: "this data fragment has been modified" is not precise enough. [Not] modified compared to what? The original bytes at the same offset? The original fragment, even though it may have a different offset now because we deleted some bytes in front of it? A simple/better solution is to add "as-is" parameter to the data-have message to inform the processor that this particular fragment is identical to some other (specified) fragment. If processor cares, it can track all these notifications and check whether the entire message is identical.)

A flag indicating that a copy of the attached application data is being kept at the OPES processor. Only the OPES processor may send this flag. This parameter can be used with any OCP message that may carry application message data. (XXX: it is yet unclear when OPES processor commitment to preserve the data may end.)

Remaining application data size prediction in octets. 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.

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.

OCP processing result. May include integer status code and textual information.

A flag indicating abnormal conditions at the sender that cannot be expressed via result parameter. It is RECOMMENDED that the recipient deletes all state associated with the corresponding OCP message.

A OCP feature identifier with optional feature parameters (sometimes called attributes). Used to declare support and negotiate use of OCP optional or extension features. This specification defines three features: TLS transport encryption (Section XXX), Raw Application Binding (Section XXX), and Processor Data Copying (Section XXX).

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 syntactically valid message (see ), subject to recipient resources limitations. If resources are exhausted or if a syntactically malformed message is received, the recipient MUST terminate processing of the corresponding connection using a Connection End (CE) message with an error flag. (XXX: the error information should identify the problem and distinguish resource limitation from syntax errors?) 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 unknown or unexpected name, parameter, or payload. Recipients MAY report (e.g., log) unknown or unexpected elements, of course. Except for messages that introduce new identifiers, all sent identifiers MUST be known (i.e., introduced and not ended by previous messages). Except for messages that introduce new identifiers, the recipient MUST ignore any message with an unknown identifier. For example, recipient must ignore a data-have message if the xid parameter refers to an unknown transaction. Message definitions below clearly state rare exceptions to the above rules. (XXX can we define "ignore"?) (XXX move these rules elsewhere?) (XXX Message parameters in [square brackets] are OPTIONAL. Other parameters are REQUIRED.)

CS none none no 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) 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) 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. If the first message received by an OPES processor is a Connection Start (CS) message, the processor MUST terminate the connection with a Connection End (CE) 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) 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 channel may be designated as a single OCP connection.

CE none [error] no both OPES processor and callout server 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 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 an 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.

SGC sg-id services none no both OPES processor and callout server 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) message is received or implied. Service groups have a connection scope. Transaction management messages do not affect existing service groups. (XXX: document that wrong sq-id lead to semantically invalid messages)

SGD sg-id none no both OPES processor and callout server Destroy Service Group (SGC) 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.

TS xid [sg-id] [services] no 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 "services" parameter applies to the original application message processed within this OCP transaction boundaries. The "sg-id" parameter refers to a service group created with a Create Service Group (SGC) 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 associated list of services as if it was specified explicitly using the "services" parameter. The "services" and "sg-id" parameters are mutually exclusive. At least one of the two parameters is REQUIRED. If none or both are given, the message is semantically invalid. This message introduces transaction identifier (xid).

TE xid, result [error] no 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). A 'xaction-end' message implies 'app-message-end' messages for all associated application messages (XXX: rephrase this and similar into a MUST?).

AMS xid, am-id none no 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 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).

AME xid, am-id, result [error] no 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 AME (Application Message End) message ends any data preservation commitments associated with the corresponding application message. This message terminates the life of the application message identifier (am-id).

DH xid, am-id, offset, size [modified], [copied], [sizep], [modp], [ack] yes 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-have and data-as-is messages (i.e., the offset of the next data message must be equal to the offset+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 size is permitted and is useful for communicating predictions without sending data. When an OPES processor sends a "copied" flag, the OPES processor MUST keep a copy of the corresponding data (the preservation commitment starts). When an "ack" flag is present, the recipient MUST respond with a 'data-ack' message.

DUY xid, am-id, offset, size, copy-am-offset none no callout server only Tells the OPES processor to use "size" bytes of data at copy-am-offset of the original application message, as if that data came from the callout server in a 'data-have am-id offset size' message. The data chunk MUST be under the preservation commitment. If the OPES processor receives a 'data-as-is> message for data not under preservation commitment, the message is invalid. The "am-id" application message identifier MUST belong to the same OCP transaction. If it does not, the message is invalid. If the data-as-is message is invalid, the OPES processor MUST abort am-id message processing (XXX: document how processing should be aborted).

data-pause xid am-id none no callout server only Sent by a callout server, the 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' 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' 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.

data-paused xid, am-id none no OPES processor only Sent by an OPES processor, the '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' 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.

data-need xid am-id offset [size-request] no 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" parameter is present, its value is the suggested data size, and it MAY be ignored by the OPES processor. An absent "size" 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 messages (XXX: should we give an OPES processor the same abilities to pause/resume message processing that a callout server has?)

DACK xid, am-id, offset, size [wont-forward] no 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. Responding with 'data-ack' messages to 'data-have' messages with a "please-ack" flag is REQUIRED. Responding with 'data-ack' messages to 'data-have' messages without an "ack" flag is OPTIONAL. Implementations SHOULD be able to support debugging mode where every 'data-have' message is acked. (XXX: should we require responses for 'data-as-is> 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 'data-ack' message means that a complete 'data-have' message has been received, but does not imply that the data has been processed in any other way. The 'data-ack' 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.

pong none [rid] [xid [am-id]] no 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. In such case, it MUST NOT have a "rid" parameter. An 'i-am-here' message MUST be sent in response to an 'are-you-there' request. The "rid" value in the response MUST be set to "rid" value of the 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.

ping none [xid [am-id]] no 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.

NO rid (list of features) none no 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) 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. 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 wither 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.

NR [feature] [Rejects] [Unknowns] no both OPES processor and callout server A Negotiation Response (NR) message conveys recipient reaction to a Negotiation Offer (NO) 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 offered features, the offering agent MUST consider negotiation failed and MAY terminate the connection. A rejected offer is indicated by omitting the "feature" parameter.

i-can [feature] none no both OPES processor and callout server An I Support (i-can) message is sent in response to a Can You Support (can-you) 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) question, indicating a partial match or a mismatch.

can-you feature none no both OPES processor and callout server A Can You Support (can-you) message solicits a declaration of support for the supplied feature, using an I Support (i-can) message. The recipient MUST respond immediately.

i-do feature none no both OPES processor and callout server

do-you feature none no both OPES processor and callout server

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

OPES treatment of IETF Internet Architecture Board (IAB) considerations are documented in [XXX].

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. 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?)

This specification defines compliance for OCP client implementations (OPES processors), OCP server implementations (callout servers), OCP application bindings, and OCP protocol extensions. Only normative parts of this specification affect compliance. Normative parts are either explicitly marked as such using the word "normative" or are phrases containing capitalized keywords from . Definitions of terms used by normative parts are, of course, normative as well. An implementation is not compliant if it fails to satisfy one or more of the MUST or REQUIRED level requirements for the protocols it implements. An implementation that satisfies all the MUST or REQUIRED level and all the SHOULD level requirements for its protocols is said to be "unconditionally compliant"; one that satisfies all the MUST level requirements but not all the SHOULD level requirements for its protocols is said to be "conditionally compliant".

Mention that transport might be L4 or above Do we really need two levels of compliance (conditional and unconditional)? document what messages cause what timers to be [re]set. Document that parameter names have message scope. A known parameter name in an unknown message does not identify a known parameter. Current syntax allows for quoting of values that do not need to be quoted. Named parameter order is also not fixed. These make digital signatures of headers impossible without interpretation. Is this a problem? replace with as-is approach How/when do OPES processor and callout server agree on meta-data format and contents? Note that meta-data should usually describe actual data encoding. Data-encoding may, however, be also negotiated. How? When? Add data-wont-use message. Document that an OPES processor can destroy data copy when data-wont-use or xaction-end message is received. Can a callout server refer to parts of [copied] data messages from the OPES processor? If yes, do we need to worry about fragmentation if yes? If no, will this restriction kill the optimization for mid-size application messages (the common case?) that are likely to be passed to the callout server in just one or two chunks? Should we support partial application message exchange (exchange only a part of the application message)? Who decides what parts to exchange? Should the callout server be able to ask which part it wants? How will it describe the part if it has not seen the entire message? 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) allow a callout server to get out of the processing loop without losing the data. Add a i-want-out server message. Document that transactions cannot cross connections, but see "fast track" todo item. Document messages that may be sent on alternative connections. Require other-connections messages to be duplicated on the primary connection. Min and max values (0 and 100) should be "commitments" rather than "probabilities". Decide whether we need a 'transactions-end' message to terminate multiple transactions efficiently. Is terminating a connection good enough? Do we need this flag or should we use result codes to relay the same meaning? 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? Can OCP be proxied above transport layer? Perhaps to implement parts of a given service, transparently to the OPES processor? To be normative, OPES Internet-Drafts must be replaced with corresponding RFCs when the latter are published.

The author gratefully acknowledges the contributions of: Abbie Barbir (Nortel Networks), Oskar Batuner (Independent Consultant), 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. Internal WG revision control ID: $Id: ocp-spec.xml,v 1.43 2003/06/06 20:28:25 rousskov Exp $ 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. 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. 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" 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. 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. 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). 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. 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). 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 connections 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