state, the EPA SHOULD perform an initial publication, i.e., a PUBLISH
request without a SIP-If-Match header field, as described in Section
4.2. The EPA MUST also discard the entity-tag that produced this
error response.
If an EPA receives a 423 (Interval Too Brief) response to a PUBLISH
request, it MAY retry the publication after changing the expiration
interval in the Expires header field to be equal to or greater than
the expiration interval within the Min-Expires header field of the
423 (Interval Too Brief) response.
6. Processing PUBLISH Requests
The Event State Compositor (ESC) is a User Agent Server (UAS) that
processes and responds to PUBLISH requests, and maintains a list of
publications for a given address-of-record. The ESC has to know
(e.g., through configuration) the set of addresses for which it
maintains event state.
The ESC MUST ignore the Record-Route header field if it is included
in a PUBLISH request. The ESC MUST NOT include a Record-Route header
field in any response to a PUBLISH request. The ESC MUST ignore the
Contact header field if one is present in a PUBLISH request.
PUBLISH requests with the same Request-URI MUST be processed in the
order that they are received. PUBLISH requests MUST also be
processed atomically, meaning that a particular PUBLISH request is
either processed completely or not at all.
When receiving a PUBLISH request, the ESC follows the steps defining
general UAS behavior in Section 8.2 of RFC 3261 [4]. In addition,
for PUBLISH specific behavior the ESC follows these steps:
1. The ESC inspects the Request-URI to determine whether this request
is targeted to a resource for which the ESC is responsible for
maintaining event state. If not, the ESC MUST return a 404 (Not
Found) response and skip the remaining steps.
It may also be that the Request-URI points to a domain that the
ESC is not responsible for. In that case, the UAS receiving the
request can assume the role of a proxy server and forward the
request to a more appropriate target.
2. The ESC examines the Event header field of the PUBLISH request.
If the Event header field is missing or contains an event package
which the ESC does not support, the ESC MUST respond to the
PUBLISH request with a 489 (Bad Event) response, and skip the
remaining steps.
3. The ESC examines the SIP-If-Match header field of the PUBLISH
request for the presence of a request precondition.
* If the request does not contain a SIP-If-Match header field,
the ESC MUST generate and store a locally unique entity-tag for
identifying the publication. This entity-tag is associated
with the event-state carried in the body of the PUBLISH
request.
* Else, if the request has a SIP-If-Match header field, the ESC
checks whether the header field contains a single entity-tag.
If not, the request is invalid, and the ESC MUST return with a
400 (Invalid Request) response and skip the remaining steps.
* Else, the ESC extracts the entity-tag contained in the SIP-If-
Match header field and matches that entity-tag against all
locally stored entity-tags for this resource and event package.
If no match is found, the ESC MUST reject the publication with
a response of 412 (Conditional Request Failed), and skip the
remaining steps.
4. The ESC processes the Expires header field value from the PUBLISH
request.
* If the request has an Expires header field, that value MUST be
taken as the requested expiration.
* Else, a locally-configured default value MUST be taken as the
requested expiration.
* The ESC MAY choose an expiration less than the requested
expiration interval. Only if the requested expiration interval
is greater than zero and less than a locally-configured
minimum, the ESC MAY reject the publication with a response of
423 (Interval Too Brief), and skip the remaining steps. This
response MUST contain a Min-Expires header field that states
the minimum expiration interval the ESC is willing to honor.
5. The ESC processes the published event state contained in the body
of the PUBLISH request. If the content type of the request does
not match the event package, or is not understood by the ESC, the
ESC MUST reject the request with an appropriate response, such as
415 (Unsupported Media Type), and skip the remainder of the steps.
* The ESC stores the event state delivered in the body of the
PUBLISH request and identified by the associated entity-tag,
updating any existing event state for that entity-tag. The
expiration value is set to the chosen expiration interval.
* If the request has no message body and contained no entity-tag,
the ESC SHOULD reject the request with an appropriate response,
such as 400 (Invalid Request), and skip the remainder of the
steps. Alternatively, in case either ESC local policy or the
event package has defined semantics for an initial publication
containing no message body, the ESC MAY accept it.
* Else, the event state identified by the entity-tag is
refreshed, setting the expiration value to the chosen
expiration interval.
* If the chosen expiration interval has a special value of "0",
the event state identified by the entity-tag MUST be
immediately removed. The ESC MUST NOT store any event state as
a result of such a request.
The processing of the PUBLISH request MUST be atomic. If internal
errors (such as the inability to access a back-end database) occur
before processing is complete, the publication MUST NOT succeed,
and the ESC MUST fail with an appropriate error response, such as
504 (Server Time-out), and skip the last step.
6. The ESC returns a 200 (OK) response. The response MUST contain an
Expires header field indicating the expiration interval chosen by
the ESC. The response MUST also contain a SIP-ETag header field
that contains a single entity-tag identifying the publication.
The ESC MUST generate a new entity-tag for each successful
publication, replacing any previous entity-tag associated with
that event state. The generated entity-tag MUST be unique from any
other entity-tags currently assigned to event state associated
with that Request-URI, and MUST be different from any entity-tag
assigned previously to event state for that Request-URI. See
Section 8.3 for more information on the ESC handling of entity-
tags.
7. Processing OPTIONS Requests
A client may probe the ESC for the support of PUBLISH using the
OPTIONS request defined in SIP [4]. The ESC processes OPTIONS
requests as defined in Section 11.2 of RFC 3261 [4]. In the response
to an OPTIONS request, the ESC SHOULD include "PUBLISH" to the list
of allowed methods in the Allow header field. Also, it SHOULD list
the supported event packages in an Allow-Events header field.
The Allow header field may also be used to specifically announce
support for PUBLISH messages when registering. (See SIP Capabilities
[12] for details).
8. Use of Entity-tags in PUBLISH
This section makes a general overview of the entity-tags usage in
PUBLISH. It is informative in nature and thus contains no normative
protocol description.
8.1. General Notes
The PUBLISH mechanism makes use of entity-tags, as defined in HTTP/
1.1 [13]. While the main functionality is preserved, the syntax and
semantics for entity-tags and the corresponding header fields is
adapted specifically for use with the PUBLISH method. The main
differences are:
o The syntax for entity-tags is a token instead of quoted-string.
There is also no prefix defined for indicating a weak entity-tag.
o A PUBLISH precondition can only apply to a single entity-tag, so
request preconditions with multiple entity-tags are not allowed.
o A request precondition can’t apply to "any" entity, namely there
is no special "*" entity-tag value defined for PUBLISH.
o Whereas in HTTP/1.1 returning an entity-tag is optional for origin
servers, in PUBLISH ESCs are required to always return an entity-
tag for a successful publication.
The main motivation for the above adaptation is that PUBLISH is
conceptually an HTTP PUT, for which only a subset of the features in
cache validation using entity-tags is allowed in HTTP/1.1. It makes
little sense to enable features other than this subset for event
state publication.
To make it apparent that the entity-tags usage in PUBLISH is similar
but not identical to HTTP/1.1, we have not adopted the header field
names directly from HTTP/1.1, but rather have created similar but
distinct names, as can be seen in Section 11.
8.2. Client Usage
Each successful publication will get assigned an entity-tag which is
then delivered to the EPA in the response to the PUBLISH request.
The EPA needs to store that entity-tag, replacing any previous
entity-tag for that event state. If a request fails with a 412
(Conditional Request Failed) response, the EPA discards the entity-
tag that caused the failure.
Entity-tags are opaque tokens to the EPA. The EPA cannot infer any
further semantics from an entity-tag beyond a simple identifier, or
assume a specific formatting. An entity-tag may be a monotonically
increasing counter, but it may also be a totally random token. It is
up to the ESC implementation as to what the formatting of an entity-
tag is.
8.3. Server Usage
Entity-tags are generated and maintained by the ESC. They are part
of the state maintained by the ESC that also includes the actual
event state and its remaining expiration interval. An entity-tag is
generated and stored for each successful event state publication, and
returned to the EPA in a 200 (OK) response. Each event state
publication from the EPA that updates a previous publication will
include an entity-tag that the ESC can use as a search key in the set
of active publications.
The way in which an entity-tag is generated is an implementation
decision. One possible way to generate an entity-tag is to implement
it as an integer counter that is incremented by one for each
successfully processed publication. Other, equally valid ways for
generating entity-tags exist, and this document makes no
recommendations or preference for a single way.
9. Controlling the Rate of Publication
As an entity responsible for aggregating state information from
potentially many sources, the ESC can be subject to considerable
amounts of publication traffic. There are ways to reduce the amount
of PUBLISH requests that the ESC receives:
o Choice of the expiration interval for a publication can be
affected by the ESC. It can insist that an EPA chooses a longer
expiration value to what it suggests, in case the ESC’s local
default minimum expiration value is not reached. Maintaining a
longer default minimum expiration value at the ESC reduces the
rate at which publications are refreshed.
o Another way of reducing publication traffic is to use a SIP-level
push-back to quench a specific source of publication traffic. To
push back on publications from a particular source, the ESC MAY
respond to a PUBLISH request with a 503 (Service Unavailable), as
defined in RFC 3261 [4]. This response SHOULD contain a Retry-
After header field indicating the time interval that the
publication source is required to wait until sending another
PUBLISH request.
At the time of writing this specification, work on managing load in
SIP is starting, which may be able to provide further tools for
managing load in event state publication systems.
10. Considerations for Event Packages using PUBLISH
This section discusses several issues which should be taken into
consideration when applying the PUBLISH mechanism to event packages.
It also demonstrates how these issues are handled when using PUBLISH
for presence publication.
Any future event package specification SHOULD include a discussion of
its considerations for using PUBLISH. At a minimum those
considerations SHOULD address the issues presented in this chapter,
and MAY include additional considerations.
10.1. PUBLISH Bodies
The body of the PUBLISH request typically carries the published event
state. Any application of the PUBLISH mechanism for a given event
package MUST define what content type or types are expected in
PUBLISH requests. Each event package MUST also describe the
semantics associated with that content type, and MUST prescribe a
default, mandatory to implement MIME type.
This document defines the semantics of the presence publication
requests (event package "presence") when the Common Profile for
Presence (CPP) Presence Information Data Format (PIDF) [6] is used.
A PUA that uses PUBLISH to publish presence state to the PA MUST
support the PIDF presence format. It MAY support other formats.
10.2. PUBLISH Response Bodies
The response to a PUBLISH request indicates whether the request was
successful or not. In general, the body of such a response will be
empty unless the event package defines explicit meaning for such a
body.
There is no such meaning for the body of a response to a presence
publication.
10.3. Multiple Sources for Event State
For some event packages, the underlying model is that of a single
entity responsible for aggregating event state (ESC), and multiple
sources, out of which only some may be using the PUBLISH mechanism.
Note that sources for event state other than those using the
PUBLISH mechanism are explicitly allowed. However, it is beyond
the scope of this document to define such interfaces.
Event packages that make use of the PUBLISH mechanism SHOULD describe
whether this model for event state publication is applicable, and MAY
describe specific mechanisms used for aggregating publications from
multiple sources.
For presence, a PUA can publish presence state for just a subset of
the tuples that may be composited into the presence document that
watchers receive in a NOTIFY. The mechanism by which the ESC
aggregates this information is a matter of local policy and out of
the scope of this specification.
10.4. Event State Segmentation
For some event packages, there exists a natural decomposition of
event state into segments. Each segment is defined as one of
potentially many identifiable sections in the published event state.
Any event package whose content type supports such segmentation of
event state, SHOULD describe the way in which these event state
segments are identified by the ESC.
In presence publication, the EPA MUST keep the "id" attributes of
tuples consistent in the context of an entity-tag. If a publication
modifies the contents of a tuple, that tuple MUST maintain its
original "id". The ESC will interpret each tuple in the context of
the entity-tag with which the request arrived. A tuple whose "id" is
missing compared to the original publication will be considered as
being removed. Similarly, a tuple is interpreted as being added if
its "id" attribute is one that the original publication did not
contain.
10.5. Rate of Publication
Controlling the rate of publication is discussed in Section 9.
Individual event packages MAY in turn define recommendations (SHOULD
or MUST strength) on absolute maximum rates at which publications are
allowed to be generated by a single EPA.
There are no rate limiting recommendations for presence publication.
11. Protocol Element Definitions
This section describes the extensions required for event publication
in SIP.
11.1. New Methods
11.1.1. PUBLISH Method
"PUBLISH" is added to the definition of the element "Method" in the
SIP message grammar. As with all other SIP methods, the method name
is case sensitive. PUBLISH is used to publish event state to an
entity responsible for compositing this event state.
Table 2 and Table 3 extend Tables 2 and 3 of RFC 3261 [4] by adding
an additional column, defining the header fields that can be used in
PUBLISH requests and responses. The keys in these tables are
specified in Section 20 of RFC 3261 [4].
+---------------------+---------+---------+
| Header Field | where | PUBLISH |
+---------------------+---------+---------+
| Accept | R | o |
| Accept | 2xx | - |
| Accept | 415 | m* |
| Accept-Encoding | R | o |
| Accept-Encoding | 2xx | - |
| Accept-Encoding | 415 | m* |
| Accept-Language | R | o |
| Accept-Language | 2xx | - |
| Accept-Language | 415 | m* |
| Alert-Info | | - |
| Allow | R | o |
| Allow | r | o |
| Allow | 405 | m |
| Allow-Events | R | o |
| Allow-Events | 489 | m |
| Authentication-Info | 2xx | o |
| Authorization | R | o |
| Call-ID | c | m |
| Call-Info | | o |
| Contact | R | - |
| Contact | 1xx | - |
| Contact | 2xx | - |
| Contact | 3xx | o |
| Contact | 485 | o |
| Content-Disposition | | o |
| Content-Encoding | | o |
| Content-Language | | o |
| Content-Length | | t |
| Content-Type | | * |
| CSeq | c | m |
| Date | | o |
| Event | R | m |
| Error-Info | 300-699 | o |
| Expires | | o |
| Expires | 2xx | m |
| From | c | m |
| In-Reply-To | R | - |
| Max-Forwards | R | m |
| Min-Expires | 423 | m |
| MIME-Version | | o |
| Organization | | o |
+---------------------+---------+---------+
Table 2: Summary of header fields, A--O
+---------------------+-----------------+---------+
| Header Field | where | PUBLISH |
+---------------------+-----------------+---------+
| Priority | R | o |
| Proxy-Authenticate | 407 | m |
| Proxy-Authenticate | 401 | o |
| Proxy-Authorization | R | o |
| Proxy-Require | R | o |
| Record-Route | | - |
| Reply-To | | - |
| Require | | o |
| Retry-After | 404,413,480,486 | o |
| Retry-After | 500,503 | o |
| Retry-After | 600,603 | o |
| Route | R | c |
| Server | r | o |
| Subject | R | o |
| Supported | R | o |
| Supported | 2xx | o |
| Timestamp | | o |
| To | c(1) | m |
| Unsupported | 420 | o |
| User-Agent | | o |
| Via | R | m |
| Via | rc | m |
| Warning | r | o |
| WWW-Authenticate | 401 | m |
| WWW-Authenticate | 407 | o |
+---------------------+-----------------+---------+
Table 3: Summary of header fields, P--Z
11.2. New Response Codes
11.2.1. "412 Conditional Request Failed" Response Code