| | | 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
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 {
uri;
};
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 {
uri;
};
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:
{"41:http://www.iana.org/assignments/opes/ocp/tls" "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.
11. Message Definitions
This section describes specific OCP messages. Each message is given
a unique name and usually has a set of anonymous and/or named
parameters. The order of anonymous parameters is specified in the
message definitions below. No particular order for named parameters
is implied by this specification. OCP extensions MUST NOT introduce
order-dependent named parameters. 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 message in valid format (see
section 3.1), subject to the limitations of the recipient’s
resources.
Unknown or unexpected message names, parameters, and payloads may be
valid extensions. For example, an "extra" named parameter may be
used for a given message, in addition to what is documented in the
message definition below. A recipient MUST ignore any valid but
unknown or unexpected name, parameter, member, or payload.
Some message parameter values use uni identifiers to refer to various
OCP states (see section 10.2 and Appendix B). These identifiers are
created, used, and destroyed by OCP agents via corresponding
messages. Except when creating a new identifier, an OCP agent MUST
NOT send a uni identifier that corresponds to an inactive state
(i.e., that was either never created or already destroyed). Such
identifiers invalidate the host OCP message (see section 5). For
example, the recipient must terminate the transaction when the xid
parameter in a Data Use Mine (DUM) message refers to an unknown or
already terminated OCP transaction.
11.1. Connection Start (CS)
CS: extends message;
A Connection Start (CS) message indicates the start of an OCP
connection. An OCP agent MUST send this message before it sends any
other message on the connection. If the first message an OCP agent
receives is not Connection Start (CS), the agent MUST terminate the
connection with a Connection End (CE) message having 400 (failure)
result status code. An OCP agent MUST send Connection Start (CS)
message exactly once. An OCP agent MUST ignore repeated Connection
Start (CS) messages.
At any time, a callout server MAY refuse further processing on an OCP
connection by sending a Connection End (CE) message with the status
code 400 (failure). Note that the above requirement to send a CS
message first still applies.
With TCP/IP as transport, raw TCP connections (local and remote peer
IP addresses with port numbers) identify an OCP connection. Other
transports may provide OCP connection identifiers to distinguish
logical connections that share the same transport. For example, a
single BEEP [RFC3080] channel may be designated as a single OCP
connection.
11.2. Connection End (CE)
CE: extends message with {
[result];
};
A Connection End (CE) Indicates the end of an OCP 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.
Connection termination without a Connection End (CE) message
indicates that the connection was prematurely closed, possibly
without the closing-side agent’s prior knowledge or intent. When an
OCP agent detects a prematurely closed connection, the agent MUST act
as if a Connection End (CE) message indicating a failure 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.
11.3. Service Group Created (SGC)
SGC: extends message with {
my-sg-id services;
};
A Service Group Created (SGC) message informs the recipient that a
list of adaptation services has been associated with the given
service group identifier ("my-sg-id"). Following this message, the
sender can refer to the group by using the identifier. The recipient
MUST maintain the association until a matching Service Group
Destroyed (SGD) message is received or the corresponding OCP
connection is closed.
Service groups have a connection scope. Transaction management
messages do not affect existing service groups.
Maintaining service group associations requires resources (e.g.,
storage to keep the group identifier and a list of service IDs).
Thus, there is a finite number of associations an implementation can
maintain. Callout servers MUST be able to maintain at least one
association for each OCP connection they accept. If a recipient of a
Service Group Created (SGC) message does not create the requested
association, it MUST immediately terminate the connection with a
Connection End (CE) message indicating a failure.
11.4. Service Group Destroyed (SGD)
SGD: extends message with {
my-sg-id;
};
A Service Group Destroyed (SGD) message instructs the recipient to
forget about the service group associated with the specified
identifier. The recipient MUST destroy the identified service group
association.
11.5. Transaction Start (TS)
TS: extends message with {
xid my-sg-id;
};
Sent by an OPES processor, a Transaction Start (TS) message indicates
the start of an OCP transaction. Upon receiving this message, the
callout server MAY refuse further transaction processing by
responding with a corresponding Transaction End (TE) 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 required "my-sg-id" identifier refers to a service group created
with an a Service Group Created (SGC) message. The callout server
MUST apply the list of services associated with "my-sg-id", in the
specified order.
This message introduces the transaction identifier (xid).
11.6. Transaction End (TE)
TE: extends message with {
xid [result];
};
A Transaction End (TE) indicates the end of the identified OCP
transaction.
An OCP agent MUST send a Transaction End (TE) message immediately
after it makes a decision to send no more messages related to the
corresponding transaction. Violating this requirement may cause, for
example, unnecessary delays, rejection of new transactions, and even
timeouts for agents that rely on this end-of-file condition to
proceed.
This message terminates the life of the transaction identifier (xid).
11.7. Application Message Start (AMS)
AMS: extends message with {
xid;
[Services: services];
};
An Application Message Start (AMS) message indicates the start of the
original or adapted application message processing and dataflow. The
recipient MAY refuse further processing by sending an Application
Message End (AME) message indicating a failure.
When an AMS message is sent by the OPES processor, the callout server
usually sends an AMS message back, announcing the creation of an
adapted version of the original application message. This
announcement may be delayed. For example, the callout server may
wait for more information from the OPES processor.
When an AMS message is sent by the callout server, an optional
"Services" parameter describes OPES services that the server MAY
apply to the original application message. Usually, the "services"
value matches what was asked by the OPES processor. The callout
server SHOULD send a "Services" parameter if its value would differ
from the list of services requested by the OPES processor. As the
same service may be known under many names, the mismatch does not
necessarily imply an error.
11.8. Application Message End (AME)
AME: extends message with {
xid [result];
};
An Application Message End (AME) message indicates the end of the
original or adapted application message processing and dataflow. The
recipient should expect no more data for the corresponding
application message.
An Application Message End (AME) message ends any data preservation
commitments and any other state associated with the corresponding
application message.
An OCP agent MUST send an Application Message End (AME) message
immediately after it makes a decision to stop processing of its
application message. Violating this requirement may cause, for
example, unnecessary delays, rejection of new transactions, and even
timeouts for agents that rely on this end-of-file condition to
proceed.
11.9. Data Use Mine (DUM)
DUM: extends message with {
xid my-offset;
[As-is: org-offset];
[Kept: org-offset org-size ];
[Modp: modp];
} and payload;
A Data Use Mine (DUM) message carries application data. It is the
only OCP Core message with a documented payload. The sender MUST NOT
make any gaps in data supplied by Data Use Mine (DUM) and Data Use
Yours (DUY) messages (i.e., the my-offset of the next data message
must be equal to the my-offset plus the payload size of the previous
data message). Messages with gaps are invalid. The sender MUST send
payload and MAY use empty payload (i.e., payload with zero size). A
DUM message without payload is invalid. Empty payloads are useful
for communicating meta-information about the data (e.g., modification
predictions or preservation commitments) without sending data.
An OPES processor MAY send a "Kept" parameter to indicate its current
data preservation commitment (section 7) for original data. When an
OPES processor sends a "Kept" parameter, the processor MUST keep a
copy of the specified data (the preservation commitment starts or
continues). The Kept offset parameter specifies the offset of the
first octet of the preserved data. The Kept size parameter is the
size of preserved data. Note that data preservation rules allow
(i.e., do not prohibit) an OPES processor to decrease offset and to
specify a data range not yet fully delivered to the callout server.
OCP Core does not require any relationship between DUM payload and
the "Kept" parameter.
If the "Kept" parameter value violates data preservation rules but
the recipient has not sent any Data Use Yours (DUY) messages for the
given OCP transaction yet, then the recipient MUST NOT use any
preserved data for the given transaction (i.e., must not sent any
Data Use Yours (DUY) messages). If the "Kept" parameter value
violates data preservation rules and the recipient has already sent
Data Use Yours (DUY) messages, the DUM message is invalid, and the
rules of section 5 apply. These requirements help preserve data
integrity when "Kept" optimization is used by the OPES processor.
A callout server MUST send a "Modp" parameter if the server can
provide a reliable value and has not already sent the same parameter
value for the corresponding application message. The definition of
"reliable" is entirely up to the callout server. The data
modification prediction includes DUM payload. That is, if the
attached payload has been modified, the modp value cannot be 0%.
A callout server SHOULD send an "As-is" parameter if the attached
data is identical to a fragment at the specified offset in the
original dataflow. An "As-is" parameter specifying a data fragment
that has not been sent to the callout server is invalid. The
recipient MUST ignore invalid "As-is" parameters. Identical means
that all adapted octets have the same numeric value as the
corresponding original octets. This parameter is meant to allow for
partial data preservation optimizations without a preservation
commitment. The preserved data still crosses the connection with the
callout server twice, but the OPES processor may be able to optimize
its handling of the data.
The OPES processor MUST NOT terminate its data preservation
commitment (section 7) in reaction to receiving a Data Use Mine (DUM)
message.
11.10. Data Use Yours (DUY)
DUY: extends message with {
xid org-offset org-size;
};
The callout server tells the OPES processor to use the "size" bytes
of preserved original data, starting at the specified offset, as if
that data chunk came from the callout server in a Data Use Mine (DUM)
message.
The OPES processor MUST NOT terminate its data preservation
commitment (section 7) in reaction to receiving a Data Use Yours
(DUY) message.
11.11. Data Preservation Interest (DPI)
DPI: extends message with {
xid org-offset org-size;
};
The Data Preservation Interest (DPI) message describes an original
data chunk by using the first octet offset and size as parameters.
The chunk is the only area of original data that the callout server
may be interested in referring to in future Data Use Yours (DUY)
messages. This data chunk is referred to as "reusable data". The
rest of the original data is referred to as "disposable data". Thus,
disposable data consists of octets below the specified offset and at
or above the (offset + size) offset.
After sending this message, the callout server MUST NOT send Data Use
Yours (DUY) messages referring to disposable data chunk(s). If an
OPES processor is not preserving some reusable data, it MAY start
preserving that data. If an OPES processor preserves some disposable
data, it MAY stop preserving that data. If an OPES processor does
not preserve some disposable data, it MAY NOT start preserving that
data.
A callout server MUST NOT indicate reusable data areas that overlap
with disposable data areas indicated in previous Data Preservation
Interest (DPI) messages. In other words, reusable data must not
grow, and disposable data must not shrink. If a callout server
violates this rule, the Data Preservation Interest (DPI) message is
invalid (see section 5).
The Data Preservation Interest (DPI) message cannot force the OPES
processor to preserve data. In this context, the term reusable
stands for callout server interest in reusing the data in the future,
given the OPES processor cooperation.
For example, an offset value of zero and the size value of 2147483647
indicate that the server may want to reuse all the original data.
The size value of zero indicates that the server is not going to send
any more Data Use Yours (DUY) messages.
11.12. Want Stop Receiving Data (DWSR)
DWSR: extends message with {
xid org-size;
};
The Want Stop Receiving Data (DWSR) message informs OPES processor
that the callout server wants to stop receiving original data any
time after receiving at least an org-size amount of an application
message prefix. That is, the server is asking the processor to
terminate original dataflow prematurely (see section 8.1) after
sending at least org-size octets.
An OPES processor receiving a Want Stop Receiving Data (DWSR) message
SHOULD terminate original dataflow by sending an Application Message
End (AME) message with a 206 (partial) status code.
An OPES processor MUST NOT terminate its data preservation commitment
(section 7) in reaction to receiving a Want Stop Receiving Data
(DWSR) message. Just like with any other message, an OPES processor
may use information supplied by Want Stop Receiving Data (DWSR) to
decide on future preservation commitments.
11.13. Want Stop Sending Data (DWSS)
DWSS: extends message with {
xid;
};
The Want Stop Sending Data (DWSS) message informs the OPES processor
that the callout server wants to stop sending adapted data as soon as
possible; the server is asking the processor for permission to
terminate adapted dataflow prematurely (see section 8.2). The OPES
processor can grant this permission by using a Stop Sending Data
(DSS) message.
Once the DWSS message is sent, the callout server MUST NOT
prematurely terminate adapted dataflow until the server receives a
DSS message from the OPES processor. If the server violates this
rule, the OPES processor MUST act as if no DWSS message were
received. The latter implies that the OCP transaction is terminated
by the processor, with an error.
An OPES processor receiving a DWSS message SHOULD respond with a Stop
Sending Data (DSS) message, provided the processor would not violate
DSS message requirements by doing so. The processor SHOULD respond
immediately once DSS message requirements can be satisfied.
11.14. Stop Sending Data (DSS)
DSS: extends message with {
xid;
};
The Stop Sending Data (DSS) message instructs the callout server to
terminate adapted dataflow prematurely by sending an Application
Message End (AME) message with a 206 (partial) status code. A
callout server is expected to solicit the Stop Sending Data (DSS)
message by sending a Want Stop Sending Data (DWSS) message (see
section 8.2).
A callout server receiving a solicited Stop Sending Data (DSS)
message for a yet-unterminated adapted dataflow MUST immediately
terminate dataflow by sending an Application Message End (AME)
message with a 206 (partial) status code. If the callout server
already terminated adapted dataflow, the callout server MUST ignore
the Stop Sending Data (DSS) message. A callout server receiving an
unsolicited DSS message for a yet-unterminated adapted dataflow MUST
either treat that message as invalid or as solicited (i.e., the
server cannot simply ignore unsolicited DSS messages).
The OPES processor sending a Stop Sending Data (DSS) message MUST be
able to reconstruct the adapted application message correctly after
the callout server terminates dataflow. This requirement implies
that the processor must have access to any original data sent to the
callout after the Stop Sending Data (DSS) message, if there is any.
Consequently, the OPES processor either has to send no data at all or
has to keep a copy of it.
If a callout server receives a DSS message and, in violation of the
above rules, waits for more original data before sending an
Application Message End (AME) response, a deadlock may occur: The
OPES processor may wait for the Application Message End (AME) message
to send more original data.
11.15. Want Data Paused (DWP)
DWP: extends message with {
xid your-offset;
};
The Want Data Paused (DWP) message indicates the sender’s temporary
lack of interest in receiving data starting with the specified
offset. This disinterest implies nothing about sender’s intent to
send data.
The "your-offset" parameter refers to dataflow originating at the OCP
agent receiving the parameter.
If, at the time the Want Data Paused (DWP) message is received, the
recipient has already sent data at the specified offset, the message
recipient MUST stop sending data immediately. Otherwise, the
recipient MUST stop sending data immediately after it sends the
specified offset. Once the recipient stops sending more data, it
MUST immediately send a Paused My Data (DPM) message and MUST NOT
send more data until it receives a Want More Data (DWM) message.
As are most OCP Core mechanisms, data pausing is asynchronous. The
sender of the Want Data Paused (DWP) message MUST NOT rely on the
data being paused exactly at the specified offset or at all.
11.16. Paused My Data (DPM)
DPM: extends message with {
xid;
};
The Paused My Data (DPM) message indicates the sender’s commitment to
send no more data until the sender receives a Want More Data (DWM)
message.
The recipient of the Paused My Data (DPM) message MAY expect the data
delivery being paused. If the recipient receives data despite this
expectation, it MAY abort the corresponding transaction with a
Transaction End (TE) message indicating a failure.
11.17. Want More Data (DWM)
DWM: extends message with {
xid;
[Size-request: your-size];
};
The Want More Data (DWM) message indicates the sender’s need for more