tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Gloss.     Arch.     IMS     UICC    |    Misc.    |    search     info

RFC 4037


Open Pluggable Edge Services (OPES) Callout Protocol (OCP) Core

Part 2 of 3, p. 15 to 33
Prev RFC Part       Next RFC Part


prevText      Top      Up      ToC       Page 15 
4.  Transactions

   An 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 the 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 the 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.

   An OCP transaction starts with a Transaction Start (TS) message sent
   by the OPES processor.  A transaction ends with the first Transaction
   End (TE) message sent or received, explicit or implied.  A TE message
   can be sent by either side.  Zero or more OCP messages associated
   with the transaction can be exchanged in between.  The figure below
   illustrates a possible message sequence (prefix "P" stands for the
   OPES processor; prefix "S" stands for the 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;

Top      Up      ToC       Page 16 
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.  In this context, "Invalid input" means
   messages or message parts that violate at least one of the normative
   rules.  A message with an invalid part is, by definition, invalid.
   If OCP agent resources are exhausted while parsing or interpreting a
   message, the agent MUST treat the corresponding OCP message as

   Unless explicitly allowed to do otherwise, an OCP agent MUST
   terminate the transaction if it receives an invalid message with
   transaction scope and MUST terminate the connection if it receives an
   invalid message with a connection scope.  A terminating agent MUST
   use the result status code of 400 and MAY specify termination cause
   information in the result status reason parameter (see section
   10.10).  If an OCP agent is unable to determine the scope of an
   invalid message it received, the agent MUST treat the message as
   having connection scope.

   OCP usually deals with optional but invasive application message
   manipulations for which 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 (making unusable) the host page while performing that
   insertion or removal.  Most OPES adaptations are high level in
   nature, which makes it impossible to assess correctness of the
   adaptations automatically, especially if "robustness guesses" are

6.  Negotiation

   The negotiation mechanism allows OCP agents to agree on the mutually
   acceptable set of features, including optional and
   application-specific behavior and OCP extensions.  For example,
   transport encryption, data format, and support for a new message can
   be negotiated.  Negotiation implies intent for a behavioral change.
   For a related mechanism allowing an agent to query capabilities of
   its counterpart without changing the counterpart's behavior, see the
   Ability Query (AQ) and Ability Answer (AA) message definitions.

   Most negotiations require at least one round trip time delay.  In
   rare cases when the other side's response is not required
   immediately, negotiation delay can be eliminated, with an inherent
   risk of an overly optimistic assumption about the negotiation

Top      Up      ToC       Page 17 
   A detected 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.

   Two core negotiation primitives are supported: negotiation offer and
   negotiation response.  A Negotiation Offer (NO) message allows an
   agent to specify a set of features from which the responder has to
   select at most one feature that it prefers.  The selection is sent by
   using a Negotiation Response (NR) message.  If the response is
   positive, both sides assume that the selected feature is in effect
   immediately (see section 11.19 for details).  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 an SMTP application profile
   enabled, as 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 (unless a negotiated feature explicitly allows
   for changing an encryption scheme on the fly).

   Negotiation Offer (NO) messages may be sent by either agent.  OCP
   extensions documenting negotiation MAY assign the initiator role to
   one of the agents, depending on the feature being negotiated.  For
   example, negotiation of transport security feature should be
   initiated by OPES processors to avoid situations where both agents
   wait for the other to make an offer.

   As 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 11.18) ensure
   that only one offer per OCP connection is honored at a time, and that
   the other concurrent offers are ignored by both agents.

6.1.  Negotiation Phase

   A Negotiation Phase is a mechanism ensuring that both agents have a
   chance to negotiate all features they require before proceeding
   further.  Negotiation Phases have OCP connection scope and do not
   overlap.  For each OCP agent, the Negotiation Phase starts with the
   first Negotiation Offer (NO) message received or the first
   Negotiation Response (NR) message sent, provided the message is not a
   part of an existing Phase.  For each OCP agent, Negotiation Phase

Top      Up      ToC       Page 18 
   ends with the first Negotiation Response (NR) message (sent or
   received), after which the agent expects no more negotiations.  Agent
   expectation rules are defined later in this section.

   During a Negotiation Phase, an OCP agent MUST NOT send messages other
   than the following "Negotiation Phase messages": Negotiation Offer
   (NO), Negotiation Response (NR), Ability Query (AQ), Ability Answer
   (AA), Progress Query (PQ), Progress Answer (PA), Progress Report
   (PR), and Connection End (CE).

   Multiple Negotiation Phases may happen during the lifespan of a
   single OCP connection.  An agent may attempt to start a new
   Negotiation Phase immediately after the old Phase is over, but it is
   possible that the other agent will send messages other than
   "Negotiation Phase messages" before receiving the new Negotiation
   Offer (NO).  The agent that starts a Phase has to be prepared to
   handle those messages while its offer is reaching the recipient.

   An OPES processor MUST make a negotiation offer immediately after
   sending a Connection Start (CS) message.  If the OPES processor has
   nothing to negotiate, the processor MUST send a Negotiation Offer
   (NO) message with an empty features list.  These two rules bootstrap
   the first Negotiation Phase.  Agents are expected to negotiate at
   least the application profile for OCP Core.  Thus, these
   bootstrapping requirements are unlikely to result in any extra work.

   Once a Negotiation Phase starts, an agent MUST expect further
   negotiations if and only if the last NO sent or the last NR received
   contained a true "Offer-Pending" parameter value.  Informally, an
   agent can keep the phase open by sending true "Offer-Pending"
   parameters with negotiation offers or responses.  Moreover, if there
   is a possibility that the agent may need to continue the Negotiation
   Phase, the agent must send a true "Offer-Pending" parameter.

6.2.  Negotiation Examples

   Below is an example of the simplest negotiation possible.  The OPES
   processor is offering nothing and is predictably receiving a
   rejection.  Note that the NR message terminates the Negotiation Phase
   in this case because neither of the messages contains a true
   "Offer-Pending" value:

   P: NO ();
   S: NR;

   The next example illustrates how a callout server can force
   negotiation of a feature that an OPES processor has not negotiated.
   Note that the server sets the "Offer-Pending" parameter to true when

Top      Up      ToC       Page 19 
   responding to the processor Negotiation Offer (NO) message.  The
   processor chooses to accept the feature:

   P: NO ();
   S: NR
      Offer-Pending: true
   S: NO ({"22:ocp://feature/example/"})
      Offer-Pending: false
   P: NR {"22:ocp://feature/example/"};

   If the server seeks to stop the above negotiations after sending a
   true "Offer-Pending" value, its only option would be send an empty
   negotiation offer (see the first example above).  If the server does
   nothing instead, the OPES processor would wait for the server and
   would eventually time out the connection.

   The following example shows a dialog with a callout server that
   insists on enabling two imaginary features: strong transport
   encryption and volatile storage for responses.  The server is
   designed not to exchange sensitive messages until both features are
   enabled.  Naturally, the volatile storage feature has to be
   negotiated securely.  The OPES processor supports one of the strong
   encryption mechanisms but prefers not to offer (to volunteer support
   for) strong encryption, perhaps for performance reasons.  The server
   has to send a true "Offer-Pending" parameter to get a chance to offer
   strong encryption (which is successfully negotiated in this case).
   Any messages sent by either agent after the (only) successful NR
   response are encrypted with "strongB" encryption scheme.  The OPES
   processor does not understand the volatile storage feature, and the
   last negotiation fails (over a strongly encrypted transport

   P: NO ({"29:ocp://example/encryption/weak"})
   S: NR
      Offer-Pending: true
   S: NO ({"32:ocp://example/encryption/strongA"},\
      Offer-Pending: true
   P: NR {"32:ocp://example/encryption/strongB"}
   ... all traffic below is encrypted using strongB ...

Top      Up      ToC       Page 20 
   S: NO ({"31:ocp://example/storage/volatile"})
      Offer-Pending: false
   P: NR
      Unknowns: ({"31:ocp://example/storage/volatile"})
   S: CSE { 400 "33:lack of VolStore protocol support" }

   The following example from [OPES-HTTP] illustrates successful HTTP
   application profile negotiation:

   P: NO ({"54:"
      Aux-Parts: (request-header,request-body)
      SG: 5;
   S: NR {"54:"
      Aux-Parts: (request-header)
      Pause-At-Body: 30
      Wont-Send-Body: 2147483647
      Content-Encodings: (gzip)
      SG: 5;

7.  'Data Preservation' 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., HTTP cookies filtering or ad
   insertion).  Yet, in many cases, the callout service has to see
   complete data.  By default, unmodified data would first travel from
   the OPES processor to the callout server and then back.  The "data
   preservation" optimization in OCP helps eliminate the return trip if
   both OCP agents cooperate.  Such cooperation is optional: OCP agents
   MAY support data preservation optimization.

   To avoid sending back unmodified data, a callout service has to know
   that the OPES processor has a copy of the data.  As data sizes can be
   very large and the callout service may not know in advance whether it
   will be able to use 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 an OPES 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) message.  The callout server MAY "use" the chunk by
   sending a Data Use Yours (DUY) message referring to the preserved

Top      Up      ToC       Page 21 
   chunk.  That OCP message does not have payload and, therefore, the
   return trip is eliminated.

   As the mapping between original and adapted data is not known to the
   processor, the processor MUST keep the announced-as-preserved chunk
   until the end of the corresponding transaction, unless the callout
   server explicitly tells the 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) message or adapted data with, for instance,
   the same offset as the preserved chunk.

   For simplicity, preserved data is always a contiguous chunk of
   original data, described by an (offset, size) pair using a "Kept"
   parameter of a Data Use Mine (DUM) message.  An OPES processor may
   volunteer to increase the size of the kept data.  An OPES processor
   may increase the offset if the callout server indicated that the kept
   data is no longer needed.

   Both agents may benefit from data reuse.  An OPES processor has to
   allocate storage to support this optimization, but 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 stop
   preserving data when the buffer becomes full.  This technique would
   benefit callout services that can quickly reuse or discard kept 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 server that
   made a decision not to send Data Use Yours (DUY) messages (for a
   specific data ranges or at all) SHOULD immediately inform the OPES
   processor of that decision with the corresponding Data Preservation
   Interest (DPI) message(s) or other mechanisms.

8.  'Premature Dataflow Termination' Optimizations

   Many callout services adapt small portions of large messages and
   would preferably not to be in the loop when that adaptation is over.
   Some callout services may not seek data modification and would
   preferably not send data back to the OPES processor, even if the OPES
   processor is not supporting the data preservation optimization
   (Section 7).  By OCP design, unilateral premature dataflow
   termination by a callout server would lead to termination of an OCP
   transaction with an error.  Thus, the two agents must cooperate to
   allow for error-free premature termination.

Top      Up      ToC       Page 22 
   This section documents two mechanisms for premature termination of
   original or adapted dataflow.  In combination, the mechanisms allow
   the callout server to get out of the processing loop altogether.

8.1.  Original Dataflow

   There are scenarios where a callout server is not interested in the
   remaining original dataflow.  For example, a simple access blocking
   or "this site is temporary down" callout service has to send an
   adapted (generated) application message but would preferably not
   receive original data from the OPES processor.

   OCP Core supports premature original dataflow termination via the
   Want Stop Receiving Data (DWSR) message.  A callout server that does
   not seek to receive additional original data (beyond a certain size)
   sends a DWSR message.  The OPES processor receiving a DWSR message
   terminates original dataflow by sending an Application Message End
   (AME) message with a 206 (partial) status code.

   The following figure illustrates a typical sequence of events.  The
   downward lines connecting the two dataflows illustrate the
   transmission delay that allows for more OCP messages to be sent while
   an agent waits for the opposing agent reaction.

   OPES                 Callout
   Processor            Server
       DUM>             <DUM
       DUM>             <DWSR  <-- Server is ready to stop receiving
       ...        _____/<DUM   <-- Server continues as usual
       DUM>______/      <DUM
       AME>             ...    <-- Processor stops sending original data
           \_____       <DUM
                        <DUM   <-- Server continues to send adapted data

   The mechanism described in this section has no effect on the adapted
   dataflow.  Receiving an Application Message End (AME) message with
   206 (partial) result status code from the OPES processor does not
   introduce any special requirements for the adapted dataflow
   termination.  However, it is not possible to terminate adapted
   dataflow prematurely after the original dataflow has been prematurely
   terminated (see section 8.3).

Top      Up      ToC       Page 23 
8.2.  Adapted Dataflow

   There are scenarios where a callout service may want to stop sending
   adapted data before a complete application message has been sent.
   For example, a logging-only callout service has to receive all
   application messages but would preferably not send copies back to the
   OPES processor.

   OCP Core supports premature adapted dataflow termination via a
   combination of Want Stop Sending Data (DWSS) and Stop Sending Data
   (DSS) messages.  A callout service that seeks to stop sending data
   sends a DWSS message, soliciting an OPES processor permission to
   stop.  While waiting for the permission, the server continues with
   its usual routine.

   An OPES processor receiving a Want Stop Sending Data message responds
   with a Stop Sending Data (DSS) message.  The processor may then pause
   to wait for the callout server to terminate the adapted dataflow or
   may continue sending original data while making a copy of it.  Once
   the server terminates the adapted dataflow, the processor is
   responsible for using original data (sent or paused after sending
   DSS) instead of the adapted data.

   The callout server receiving a DSS message terminates the adapted
   dataflow (see the Stop Sending Data (DSS) message definition for the
   exact requirements and corner cases).

   The following figure illustrates a typical sequence of events,
   including a possible pause in original dataflow when the OPES
   processor is waiting for the adapted dataflow to end.  The downward
   lines connecting the two dataflows illustrate the transmission delay
   that allows for more OCP messages to be sent while an agent waits for
   the opposing agent reaction.

Top      Up      ToC       Page 24 
   OPES                 Callout
   Processor            Server
       DUM>             <DUM
       DUM>             <DWSS    <-- Server is ready to stop sending
       ...        _____/<DUM     <-- Server continues as usual,
       DUM>______/      <DUM         waiting for DSS
       DSS>             ...
           \_____       <DUM
     possible    \______<DUM
     org-dataflow       <AME 206 <-- Server terminates adapted dataflow
     pause        _____/             upon receiving the DSS message
       DUM>                      <-- Processor resumes original dataflow
       DUM>                          to the server and starts using
       ...                           original data without adapting it

   Premature adapted dataflow preservation is not trivial, as the OPES
   processor relies on the callout server to provide adapted data
   (modified or not) to construct the adapted application message.  If
   the callout server seeks to quit its job, special care must be taken
   to ensure that the OPES processor can construct the complete
   application message.  On a logical level, this mechanism is
   equivalent to switching from one callout server to another
   (non-modifying) callout server in the middle of an OCP transaction.

   Other than a possible pause in the original dataflow, the mechanism
   described in this section has no effect on the original dataflow.
   Receiving an Application Message End (AME) message with 206 (partial)
   result status code from the callout server does not introduce any
   special requirements for the original dataflow termination.

8.3.  Getting Out of the Loop

   Some adaptation services work on application message prefixes and do
   not seek to be in the adaptation loop once their work is done.  For
   example, an ad insertion service that did its job by modifying the
   first fragment of a web "page" would not seek to receive more
   original data or to perform further adaptations.  The 'Getting Out of
   the Loop' optimization allows a callout server to get completely out
   of the application message processing loop.

   The "Getting Out of the Loop" optimization is made possible by
   terminating the adapted dataflow (section 8.2) and then by
   terminating the original dataflow (section 8.1).  The order of
   termination is very important.

Top      Up      ToC       Page 25 
   If the original dataflow is terminated first, the OPES processor
   would not allow the adapted dataflow to be terminated prematurely, as
   the processor would not be able to reconstruct the remaining portion
   of the adapted application message.  The processor would not know
   which suffix of the remaining original data has to follow the adapted
   parts.  The mapping between original and adapted octets is known only
   to the callout service.

   An OPES processor that received a DWSS message followed by a DWSR
   message MUST NOT send an AME message with a 206 (partial) status code
   before sending a DSS message.  Informally, this rule means that a
   callout server that wants to get out of the loop fast should send a
   DWSS message immediately followed by a DWSR message; the server does
   not have to wait for the OPES processor's permission to terminate
   adapted dataflow before requesting that the OPES processor terminates
   original dataflow.

9.  Protocol Element Type Declaration Mnemonic (PETDM)

   A protocol element type is a named set of syntax and semantics rules.
   This section defines a simple, formal declaration mnemonic for
   protocol element types, labeled PETDM.  PETDM simplicity is meant to
   ease type declarations in this specification.  PETDM formality is
   meant to improve interoperability among implementations.  Two
   protocol elements are supported by PETDM: message parameter values
   and messages.

   All OCP Core parameter and message types are declared by using PETDM.
   OCP extensions SHOULD use PETDM when declaring new types.

   Atom, list, structure, and message constructs are four available base
   types.  Their syntax and semantics rules are defined in section 3.1.
   New types can be declared in PETDM to extend base types semantics by
   using the following declaration templates.  The new semantics rules
   are meant to be attached to each declaration using prose text.

   Text in angle brackets "<>" are template placeholders, to be
   substituted with actual type names or parameter name tokens.  Square
   brackets "[]" surround optional elements such as structure members or
   message payload.

   o  Declaring a new atomic type:
   <new-type-name>: extends atom;

   o  Declaring a new list with old-type-name items:
   <new-type-name>: extends list of <old-type-name>;
   Unless it is explicitly noted otherwise, empty lists are valid and
   have the semantics of an absent parameter value.

Top      Up      ToC       Page 26 
   o  Declaring a new structure with members:
   <new-type-name>: extends structure with {
           <old-type-nameA> <old-type-nameB> [<old-type-nameC>] ...;
           <member-name1>: <old-type-name1>;
           <member-name2>: <old-type-name2>;
           [<member-name3>: <old-type-name3>];

   The new structure may have anonymous members and named members.
   Neither group has 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

   o  Declaring a new message with parameters:
   <new-type-name>: extends message with {
           <old-type-nameA> <old-type-nameB> [<old-type-nameC>] ...;
           <parameter-name1>: <old-type-name1>;
           <parameter-name2>: <old-type-name2>;
           [<parameter-name3>: <old-type-name3>];

   The new type name becomes the message name.  Just as when a structure
   is extended, the new message may have anonymous parameters and named
   parameters.  Neither group has to exist.  Note that it is always
   possible for extensions to add more parameters to old messages
   without affecting type semantics because unrecognized parameters are
   ignored by compliant agents.

   o  Extending a type with more semantics details:

   <new-type-name>: extends <old-type-name>;

   o  Extending a structure- or message-base type:
   <new-type-name>: extends <old-type-name> with {
           <old-type-nameA> <old-type-nameB> [<old-type-nameC>] ...;
           <member-name1>: <old-type-name1>;
           <member-name2>: <old-type-name2>;
           [<member-name3>: <old-type-name3>];
   New anonymous members are appended to the anonymous members of the
   old type, and new named members are merged with named members of the
   old type.

Top      Up      ToC       Page 27 
   o  Extending a message-base type with payload semantics:
   <new-type-name>: extends <old-type-name> with {
   } and payload;
   Any any OCP message can have payload, but only some message types
   have known payload semantics.  Like any parameter, payload may be
   required or optional.

   o  Extending type semantics without renaming the type:
   <old-type-name>: extends <namespace>::<old-type-name>;
   The above template can be used by OCP Core extensions that seek to
   change the semantics of OCP Core types without renaming them.  This
   technique is essential for extending OCP messages because the message
   name is the same as the message type name.  For example, an SMTP
   profile for OCP might use the following declaration to extend an
   Application Message Start (AMS) message with Am-Id, a parameter
   defined in that profile:

   AMS: extends Core::AMS with {
           Am-Id: am-id;

   All extended types may be used as replacements of the types they
   extend.  For example, a Negotiation Offer (NO) message uses a
   parameter of type Features.  Features (section 10.12) is a list of
   feature (section 10.11) items.  A Feature is a structure-based type.
   An OCP extension (e.g., an HTTP application profile) 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 feature items and negotiate accordingly.  Other
   recipients will ignore them.

   The OCP Core namespace tag is "Core".  OCP extensions that declare
   types MUST define their namespace tags (so that other extensions and
   documentation can use them in their PETDM declarations).

9.1.  Optional Parameters

   Anonymous parameters are positional: The parameter's position (i.e.,
   the number of anonymous parameters to the left) is its "name".  Thus,
   when a structure or message has multiple optional anonymous
   parameters, parameters to the right can be used only if all
   parameters to the left are present.  The following notation

   [name1] [name2] [name3] ... [nameN]

   is interpreted as

Top      Up      ToC       Page 28 
   [name1 [ name2 [ name3 ... [nameN] ... ]]]

   When an anonymous parameter is added to a structure or message that
   has optional anonymous parameters, the new parameter has to be
   optional and can only be used if all old optional parameters are in
   use.  Named parameters do not have these limitations, as they are not
   positional, but associative; they are identified by their explicit
   and unique names.

10.  Message Parameter Types

   This section defines parameter value types that are used for message
   definitions (section 11).  Before using a parameter value, an OCP
   agent MUST check whether the value has the expected type (i.e.,
   whether it complies with all rules from the type definition).  A
   single 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 the type of every new protocol element they introduce.

10.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.  Uni semantics is incomplete without the scope
   specification.  Many uri parameters are URLs.  Unless it is noted
   otherwise, URL identifiers do not imply the existence of a
   serviceable resource at the location they specify.  For example, an
   HTTP request for an HTTP-based URI identifier may result in a 404
   (Not Found) response.

10.2.  uni

   uni: extends atom;

   Uni (unique numeric identifier) is an atom formatted as dec-number
   and with a value in the [0, 2147483647] range, inclusive.

   A uni parameter is used as a unique (within a given scope)
   identifier.  Uni semantics is incomplete without the scope
   specification.  Some OCP messages create identifiers (i.e., bring
   them into scope).  Some OCP messages destroy them (i.e, remove them

Top      Up      ToC       Page 29 
   from scope).  An OCP agent MUST NOT create the same uni value more
   than once within the same scope.  When creating a new identifier of
   the same type and within the same scope as some old identifier, an
   OCP agent MUST use a higher numerical value for the new identifier.
   The first rule makes uni identifiers suitable for cross-referencing
   logs and other artifacts.  The second rule makes efficient checks of
   the first rule possible.

   For example, a previously used transaction identifier "xid" must not
   be used for a new Transaction Start (TS) message within the same OCP
   transaction, even if a prior Transaction End (TE) message was sent
   for the same transaction.

   An OCP agent MUST terminate the state associated with uni uniqueness
   scope if all unique values have been used up.

10.3.  size

   size: extends atom;

   Size is an atom formatted as dec-number and with a value in the [0,
   2147483647] range, inclusive.

   Size value is the number of octets in the associated data chunk.

   OCP Core cannot handle application messages that exceed 2147483647
   octets in size, that require larger sizes as a part of OCP marshaling
   process, or that use sizes with granularity other than 8 bits.  This
   limitation can be addressed by OCP extensions, as hinted in section

10.4.  offset

   offset: extends atom;

   Offset is an atom formatted as dec-number and with a value in the [0,
   2147483647] range, inclusive.

   Offset is an octet position expressed in the number of octets
   relative to the first octet of the associated dataflow.  The offset
   of the first data octet has a value of zero.

10.5.  percent

   percent: extends atom;

   Percent is an atom formatted as dec-number and with a value in the
   [0, 100] range, inclusive.

Top      Up      ToC       Page 30 
   Percent semantics is incomplete unless its value is associated with a
   boolean statement or assertion.  The value of 0 indicates absolute
   impossibility.  The value of 100 indicates an absolute certainty.  In
   either case, the associated statement can be relied upon as if it
   were expressed in boolean rather than probabilistic terms.  Values in
   the [1,99] inclusive range indicate corresponding levels of certainty
   that the associated statement is true.

10.6.  boolean

   boolean: extends atom;

   Boolean type is an atom with two valid values: true and false.  A
   boolean parameter expresses the truthfulness of the associated

10.7.  xid

   xid: extends uni;

   Xid, an OCP transaction identifier, uniquely identifies an OCP
   transaction within an OCP connection.

10.8.  sg-id

   sg-id: extends uni;

   Sg-id, a service group identifier, uniquely identifies a group of
   services on an OCP connection.

10.9.  modp

   modp: extends percent;

   Modp extends the percent type to express the sender's confidence that
   application data will be modified.  The boolean statement associated
   with the percentage value is "data will be modified".  Modification
   is defined as adaptation that changes the numerical value of at least
   one data octet.

10.10.  result

   result: extends structure with {
           atom [atom];

   The OCP processing result is expressed as a structure with two
   documented members: a required Uni status code and an optional

Top      Up      ToC       Page 31 
   reason.  The reason member contains informative textual information
   not intended for automated processing.  For example:

   { 200 OK }
   { 200 "6:got it" }
   { 200 "27:27 octets in UTF-8 encoding" }

   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 a 200 |
   |        |              | status code recipient.                    |
   |    206 |    partial   | Partial success.  This status code is     |
   |        |              | documented for Application Message End    |
   |        |              | (AME) messages only.  The code indicates  |
   |        |              | that the agent terminated the             |
   |        |              | corresponding dataflow prematurely (i.e., |
   |        |              | more data would be needed to reconstruct  |
   |        |              | a complete application message).          |
   |        |              | Premature termination of one dataflow     |
   |        |              | does not introduce any special            |
   |        |              | requirements for the other dataflow       |
   |        |              | termination.  See dataflow termination    |
   |        |              | optimizations (section 8) for use cases.  |
   |    400 |    failure   | An error, exception, or trouble.  A       |
   |        |              | recipient of a 400 (failure) result of an |
   |        |              | AME, TE, or CE message MUST destroy any   |
   |        |              | state or data associated with the         |
   |        |              | corresponding dataflow, transaction, or   |
   |        |              | connection.  For example, an 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 made possible by adding new "result"
   structure members or by negotiating additional result codes (e.g., as
   a part of a negotiated profile).  A recipient of an unknown (in

Top      Up      ToC       Page 32 
   then-current context) result code MUST act as if code 400 (failure)
   were received.

   The recipient of a message without the actual result parameter, but
   with an optional formal result parameter, MUST act as if code 200
   (OK) were received.

   Textual information (the second anonymous parameter of the result
   structure) is often referred to as "reason" or "reason phrase".  To
   assist manual troubleshooting efforts, OCP agents are encouraged to
   include descriptive reasons with all results indicating a failure.

   In this specification, an OCP message with result status code of 400
   (failure) is called "a message indicating a failure".

10.11.  feature

   feature: extends structure with {

   The feature type extends structure to relay an OCP feature identifier
   and to reserve a "place" for optional feature-specific parameters
   (sometimes called feature attributes).  Feature values are used to
   declare support for and to negotiate use of OCP features.

   This specification does not define any features.

10.12.  features

   features: extends list of feature;

   Features is a list of feature values.  Unless it is noted otherwise,
   the list can be empty, and features are listed in decreasing
   preference order.

10.13.  service

   service: extends structure with {

   Service structure has one anonymous member, an OPES service
   identifier of type uri.  Services may have service-dependent
   parameters.  An OCP extension defining a service for use with OCP
   MUST define service identifier and service-dependent parameters, if
   there are any, as additional "service" structure members.  For
   example, a service value may look like this:

Top      Up      ToC       Page 33 
   {"41:" "8:blowfish"}

10.14.  services

   services: extends list of service;

   Services is a list of service values.  Unless it is noted otherwise,
   the list can be empty, and the order of the values is the requested
   or actual service application order.

10.15.  Dataflow Specializations

   Several parameter types, such as offset apply to both original and
   adapted dataflow.  It is relatively easy to misidentify a type's
   dataflow affiliation, especially when parameters with different
   affiliations are mixed together in one message declaration.  The
   following statements declare new dataflow-specific types by using
   their dataflow-agnostic versions (denoted by a <type> placeholder).

   The following new types refer to original data only:

   org-<type>: extends <type>;

   The following new types refer to adapted data only:

   adp-<type>: extends <type>;

   The following new types refer to the sender's dataflow only:

   my-<type>: extends <type>;

   The following new types refer to the recipient's dataflow only:

   your-<type>: extends <type>;

   OCP Core uses the above type-naming scheme to implement dataflow
   specialization for the following types: offset, size, and sg-id.  OCP
   extensions SHOULD use the same scheme.

(page 33 continued on part 3)

Next RFC Part