Internet-Draft | PREP | July 2024 |
Gupta | Expires 17 January 2025 | [Page] |
- Workgroup:
- HTTP
- Internet-Draft:
- draft-gupta-httpbis-per-resource-events-01
- Published:
- Intended Status:
- Standards Track
- Expires:
Per Resource Events
Abstract
Per Resource Events is a minimal protocol built on top of HTTP that allows clients to receive notifications directly from any resource of interest. The Per Resource Events Protocol (PREP) is predicated on the idea that the most intuitive source for notifications about changes made to a resource is the resource itself.¶
About This Document
This note is to be removed before publishing as an RFC.¶
The latest revision of this draft can be found at https://CxRes.github.io/prep/draft-gupta-httpbis-per-resource-events.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-gupta-httpbis-per-resource-events/.¶
Discussion of this document takes place on the HTTP Working Group mailing list (mailto:ietf-http-wg@w3.org), which is archived at https://lists.w3.org/Archives/Public/ietf-http-wg/.¶
Source for this draft and an issue tracker can be found at https://github.com/CxRes/prep.¶
Status of This Memo
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 17 January 2025.¶
Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
1. Introduction
The Per Resource Events Protocol defines a minimal HTTP-based framework by which clients can securely receive update notifications directly from any resource of interest on the Open Web Platform.¶
1.1. Motivation
HTTP was originally designed to transfer a static documents within a single request and response. If the document changes, HTTP does not automatically update clients with the new versions. This design was adequate for web pages that were mostly static and written by hand.¶
But web-applications today are dynamic. They provide (near-)instantaneous updates across multiple clients and servers. The many workarounds developed over the years to provide real-time updates over HTTP have often proven to be inadequate. Web programmers instead resort to implementing custom messaging systems over alternate protocols such as WebSockets, which requires additional layers of code in the form of non-standard JavaScript frameworks to synchronize changes of state.¶
Per Resource Events is a minimal protocol built on top of HTTP that allows clients to receive notifications directly from a resource of interest. Unlike other HTTP based solutions, Per Resource Events Protocol supports the use of arbitrary media-types for notifications, which can be negotiated just like representations; thus giving implementers a lot of flexibility to customize notifications according to the needs of their application.¶
1.2. How it Works
Consider an ordinary HTTP GET
request:¶
A client application that wishes to receive PREP notifications from a resource simply makes a GET
request with just one additional Accept-Events
header.¶
Additional parameters might be added to the Accept-Events
header to negotiate the form of notifications as discussed in Section 7, Request.¶
If a server does not implement the Per Resource Events Protocol, the Accept-Events
header in a GET
request is simply ignored. The resource returns the current representation thereby preserving backwards compatibility. Let us presume this response is:¶
However, if the server supports the Per Resource Events Protocol, it sends a multipart response with the current representation followed any notifications.¶
The response now includes an additional Events
headers which specifies prep
as the notifications protocol and a status for the notifications response. As a courtesy, the response also includes the Vary
header to indicate that response was influenced by the Accept-Events
header in the request and the Accept-Events
header itself for reactive negotiation in the future.¶
The Content-type
header now indicates a response body of multipart/mixed
to reflect the two part response. Thus, we have the following response headers:¶
The first part of this multipart response is the current representation of the resource:¶
The client can request for this to be skipped by specifying a Last-Event-Id
header set either to the ID of the previous representation or *
as described in Section 7.¶
The second part of this multipart response is itself a multipart message that contains notifications. Upon a resource event, a notification is transmitted as a part of this multipart message.¶
By default, notifications are sent in the message/rfc822
format (which is structurally identical to a HTTP/1.1 message) with some additional semantics as specified in Section 10. Alternate formats and semantics might be negotiated using the Accept-Events
header.¶
The response stream is closed when the time limit for notification has elapsed or immediately after the resource is deleted as in the example below:¶
Together, the complete response with PREP notifications is:¶
1.3. Scope
The Per Resource Events Protocol specifies:¶
-
a mechanism for the discovery of notification capabilities per resource,¶
-
a mechanism to request notifications from a resource,¶
-
representation and semantics for the response that transmits notifications,¶
-
a default representation for notifications and associated semantics when used to transmit notifications.¶
The Per Resource Events Protocol does not specify:¶
-
a specific authentication and authorization mechanism to be used with the Per Resource Events Protocol. Implementations are encouraged to use existing approaches for authentication and authorization.¶
-
representation and semantics for notifications (other than the default case).¶
-
Implementations are free to use any media-type for notifications, which can be negotiated just like representations.¶
-
Implementations are also free to define additional semantics for a given media-type, when used to transmit notifications using the Per Resource Events Protocol.¶
-
1.4. Audience
This specification is for:¶
-
Server developers who wish to enable clients to listen for updates to particular resources.¶
-
Application developers who wish to implement a client to listen for updates to particular resources.¶
2. Design
The Per Resource Events Protocol is predicated on a resource being the most intuitive source for notifications about its own updates.¶
This is unlike other notification protocols that require additional resources to be specifically dedicated as endpoints for delivering notifications. Servers that provide updates are forced to maintain these additional endpoints and clients that consume these updates have to co-ordinate data between the endpoint and a resource of interest.¶
By giving every resource the ability to send notifications when it updates, the Per Resource Events Protocol aims to reduce the complexity of both servers and clients implementing notifications; thus, making it easier for developers to build and maintain real-time applications.¶
2.1. Principles
The Per Resource Events Protocol treats notifications as a temporally extended representation of any resource. That is, a representation can describe not (just) the state of the resource but events on the resource. With HTTP allowing representations to provide a potentially unbounded stream of data, the Per Resource Events Protocol is able to communicate events on the resource as notifications.¶
2.2. Goals
The goals of the Per Resource Events Protocol are:¶
-
to provide notifications only using the HTTP protocol STD97 [HTTP] so that the clients are able to request for update notifications using the Fetch API [FETCH].¶
-
to provide updates directly from the resource of interest, obliviating the need to connect to another endpoint for notifications, minimizing round-trips between clients and servers and the need to co-ordinate responses between a resource and the endpoint.¶
-
to allow arbitrary representations for notifications. Implementers shall be able to provide notifications that are potentially more expressive when compared to existing HTTP based messaging protocols such as Server Sent Events [SSE].¶
2.3. Constraints
To the extent feasible, the Per Resource Events Protocol:¶
-
adheres to established practices and conventions. In particular, every attempt has been made to reuse existing protocols and specifications. Implementers shall be able to repurpose existing tools and libraries for implementing this specification.¶
-
conforms to the REST Architectural Style [REST] and best practices for Building Protocols with HTTP [RFC9205]. This specification can, thus, be used to extend the capabilities of any existing HTTP resource to provide notifications. Implementers shall be able to scale notifications along with their data/applications.¶
2.4. Known Limitations
The Per Resource Events Protocol only allows notifications to be sent for events on a given resource. It is not possible for resources to send notifications for arbitrary events such as state changes on multiple resources or combinations thereof. Implementations using Per Resource Events Protocol have to create separate resources to realize such notification endpoints. But this is no different from APIs built on top of existing messaging protocols (See, for example, [WS] and [WEBSUB]).¶
Due to the limits on connections per domain, the Per Resource Events Protocol is not suitable for use with HTTP/1.1, especially when providing notifications for multiple resource from the same domain that might be accessed simultaneously. This limitation is identical to that of other HTTP based streaming based protocols such as Server-Sent Events [SSE]. Implementations are strongly encouraged to adopt HTTP/2 (or later) and implement mitigation strategies, such as to maximize the number of concurrent connections and to provide alternate locations for resources on different domains.¶
3. Conformance
3.1. Document Conventions
All assertions, diagrams, examples and notes in this specification are non-normative.¶
3.2. Requirements Notation
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
3.3. Classes of Products
The Per Resource Events Protocol identifies the following Classes of Products for conforming implementations. These products are referenced throughout this specification.¶
-
Resource Server
-
that builds on HTTP origin server ([HTTP], Section 3.6) by defining header fields ([HTTP], Section 6.3) and media types ([HTTP], Section 8.3.1).¶
-
Application Client
-
that builds on HTTP user agent ([HTTP], Section 3.5) by defining behaviour in terms of fetching [FETCH] across the platform.¶
3.4. Interoperability
Interoperability occurs between Application Client—Resource Server (Section 3.4) as defined by the Per Resource Events Protocol.¶
-
Application Client—Resource Server Interoperability
-
Interoperability of implementations for application clients and resource servers is tested by evaluating an implementation's ability to request and respond to HTTP messages that conform to the Per Resource Events Protocol.¶
3.5. Terminology
The following terms are defined:¶
-
A message sent to application clients (that had previously requested it) when an HTTP request made on a resource fulfils some specified criteria.¶
-
Base Response
-
The response that would have been returned, were notifications not requested for, in an otherwise identical HTTP request.¶
-
Event Field
-
A parameter for a protocol item in the
Accept-Events
header field or a member of theEvents
header field.¶
4. Header Fields
The Per Resource Events Protocol introduces new header fields. These header fields are not specific to the Per Resource Events Protocol. They can be used by other protocols that augment resources with the ability to send notifications.¶
Protocols MUST ensure that the semantics be so defined that these header fields are safely ignored by recipients that do not recognize them ([HTTP], Section 5.1).¶
4.1. Accept-Events
The Accept-Events
header field can be used by application clients to specify their preferred protocol for receiving notifications. For example, the Accept-Events
header field can be used to indicate that the request is specifically limited to a small set of desired protocols, as in the case for notifications with the Per Resource Events Protocol.¶
When sent by a resource server in a response, the Accept-Events
header field provides information about which notification protocols are preferred in a subsequent request to the same resource.¶
An application client MAY generate a request for notifications regardless of having received an Accept-Events
header field. The information only provides advice for the sake of improving performance and reducing unnecessary network transfers.¶
Conversely, an application client MUST NOT assume that receiving an Accept-Events
header field means that future requests will return notifications. The content might change, the server might only support notifications requests at certain times or under certain conditions, or a different intermediary might process the next request.¶
4.1.1. Validity
A recipient MUST ignore the Accept-Events
header field received with a request method that is unrecognized or for which notifications response is not defined for a particular notifications protocol.¶
A recipient MUST ignore the Accept-Events
header field received in response to a request method that is unrecognized or for which notifications discovery and/or response is not defined for a particular notifications protocol.¶
A recipient MUST ignore the Accept-Events
header field that it does not understand.¶
A recipient MUST ignore the protocols specified in the Accept-Events
header field that they are not aware of.¶
4.1.2. Syntax
Accept-Events
is a List structured ([HTTP-SF], Section 3.1) header field*. Its members MUST be of type string that identifies a notification protocol. A protocol identifier MAY be followed with zero or more parameters defined by the given protocol, which MAY be followed by a q
parameter.¶
The q
parameter assigns a relative "weight" to the sender's preference for a notification protocol with semantics as defined in [HTTP], Section 12.4.2. Senders using weights SHOULD send q
last (after all protocol parameters). Recipients SHOULD process any parameter named q
as weight, regardless of parameter ordering.¶
Note: Use of the q
parameter name to negotiate notification protocols would interfere with any parameter having the same name. Hence, protocol parameters named q
are disallowed.¶
4.2. Events
The Events
header field is sent by a resource server to provide event fields in response to a request for notifications.¶
Where the Accept-Events
header field sent in the request is ignored, a resource server MUST NOT send the Events
header field in a response.¶
Conversely, a resource server MUST send the Events
header field in a response, if the Accept-Events
header field sent in the request is not ignored.¶
4.2.1. Validity
If the Events
header field is sent in response to a request that does not contain the Accept-Events
header field, the recipient MUST treat the response as invalid.¶
If the response contains a Events
header field that the recipient does not understand or the Events
header field specifies a protocol
that the recipient does not understand, the recipient MUST NOT process the response. A proxy that receives such a message SHOULD forward it downstream.¶
4.2.2. Syntax
Events
is a Dictionary structured ([HTTP-SF], Section 3.1) header field*. It MUST contain one member with the key protocol
whose value identifies the notification protocol used in the response. It MAY contain other members that are defined by the given notification protocol.¶
5. Protocol
5.1. Event Fields
The Per Resource Events Protocol reuses existing HTTP fields ([HTTP], Section 5) as event fields. Any HTTP field MAY be used as an event field. For the limited context of notifications using the Per Resource Events Protocol, an event field with the same name as an HTTP field MUST have identical semantics to that HTTP field, unless otherwise specified.¶
This specification restricts Accept-Events
and Events
as Structured header fields* [HTTP-SF]. From this it follows:¶
-
An event field whose value is anything except a bare Item, that is, an Item without Parameters, MUST be specified inside an Inner List.¶
-
Unless otherwise specified, an event field that is not already defined as a Structured Field, therefore, MUST be handled as a Retrofit Structured Field [HTTP-Retrofit] when such handling is defined.¶
-
An event field that is not already defined as a Structured Field but cannot be handled as a Retrofit Structured Field either, MUST be explicitly specified by the implementation.¶
5.2. Methods
For the Per Resource Events Protocol, HEAD
([HTTP], Section 9.3.2) and GET
([HTTP], Section 9.3.1) are the only methods in response to which notifications are advertised.¶
A resource server MUST NOT send the Accept-Events
header field with prep
as a protocol in response to a request with any method other than HEAD
or GET
.¶
For the Per Resource Events Protocol, GET
([HTTP], Section 9.3.1) is the only method by which notifications are requested and for which notifications response is defined.¶
An application client MUST NOT send the Accept-Events
header field with prep
as a protocol in a request with any method other than GET
.¶
A resource server MUST NOT send the Events
header field with the parameter protocol
with a value of prep
in response to a request with any method other than GET
.¶
A resource server MUST NOT send the Events
header field except in response to a GET
request.¶
5.3. Status Codes
The Per Resource Events Protocol reuses existing HTTP status codes ([HTTP], Section 15) to describe the result of the request for notifications and the semantics of notifications in the response.¶
In response to a request where Accept-Events
header field indicates prep
as the preferred protocol, a resource server that supports notifications using the Per Resource Events Protocol MUST communicate the status code for the notifications response using the status
parameter in the Events
header field.¶
For the limited context of notifications using the Per Resource Events Protocol, the status code communicated using the status
parameter in the Events
header field MUST have identical semantics to the corresponding HTTP status code, unless otherwise specified.¶
6. Discovery
Application clients can engage in reactive content negotiation to discover if a resource server supports notifications using the Per Resource Events Protocol on a given resource.¶
6.1. Request
An application client can discover the ability of a resource server to deliver PREP notifications for a target resource by sending a HEAD
([HTTP], Section 9.3.2) request.¶
6.2. Not Available
In the response to a HEAD
request, a resource server that does not provide notifications for the target resource using the Per Resource Events Protocol MUST NOT list prep
as as one of the available protocols in the Accept-Events
header field.¶
6.3. Available
In response to a HEAD
request, a resource server that serves notifications for the target resource using the Per Resource Events Protocol SHOULD include the Accept-Events
header field, which MUST list prep
as one of the available protocols.¶
Associated with prep
list item, the resource server MUST include an accept
event field with at least one acceptable media-type for notifications.¶
7. Request
The Per Resource Events Protocol extends the content negotiation mechanism provided by HTTP allowing application clients to negotiate notifications independent of the base response.¶
In order to receive notifications using the Per Resource Events Protocol from a resource, an application client sends a GET
request to resource server, which:¶
-
MUST include the
Accept-Events
header field, which:¶-
MUST list
prep
as a preferred notification protocol.¶-
MAY include zero or more event fields. For example, application clients MAY specify an
accept
event field to indicate a preferred media-type for notifications.¶
-
-
-
MAY include the
Last-Event-ID
header field ([SSE], Section 9.2.4) requesting the resource server to not send the base response body and resume notifications from the event occurring immediately after the one specified.¶
A resource server MUST ignore event fields for prep
notifications in the Accept-Events
header that it does not recognize or implement.¶
8. Response without Notifications
8.1. Not Available
A resource server not implementing the Per Resource Events Protocol (or not supporting it for the target resource) can ignore a request for notifications and respond as if it received a normal request on that resource without impacting interoperability.¶
A resource server that does not provide notifications using the Per Resource Events Protocol MUST NOT:¶
-
list
prep
as as one of the available protocols in theAccept-Events
header field, if sent in the response.¶ -
send the
Events
header field in the response with theprotocol
event field set toprep
.¶
8.2. Error Response
A resource server MUST NOT include PREP notifications in a response, unless request results in one of the following status codes:¶
-
200 (OK)
([HTTP], Section 15.3.1),¶ -
204 (No Content)
([HTTP], Section 15.3.5),¶ -
206 (Partial Content)
([HTTP], Section 15.3.7),¶ -
226 (IM Used)
([Delta], Section 10.4.1).¶
A resource server that does not serve PREP notifications, on account of the response not having one of the above-mentioned status codes:¶
-
SHOULD include the
Events
header fields where:¶-
the
protocol
event field MUST be set to a value ofprep
,¶ -
the
status
event field MUST be set to412 (Precondition Failed)
([HTTP], Section 15.5.13) status code.¶
-
8.3. Notification Errors
A resource server might still not be able to send notifications using the Per Resource Events Protocol requested by an application client despite a valid response.¶
A resource server unable to serve PREP notifications, even when the request results in a status code mentioned in Section 8.2:¶
-
SHOULD include the
Events
header fields in the response where:¶-
the
protocol
event field MUST be set to a value ofprep
,¶ -
the
status
event field MUST be set to appropriate status code indicating the reason for not serving notifications.¶
-
9. Notifications Response
9.1. Headers
A resource server providing notifications using the Per Resource Events Protocol:¶
-
MUST include the following header fields in the response:¶
-
Date
([HTTP], Section 6.6.1).¶ -
Content-Type
([HTTP], Section 8.3) with the media type set tomultipart/mixed
([RFC2046], Section 5.1.3).¶ -
Events
which MUST include the following event fields:¶-
protocol
set to the valueprep
.¶ -
status
set to the200 (OK)
([HTTP], Section 15.3.1) status code.¶ -
expires
with an integer value in seconds indicating an interval afterDate
when notifications will no longer be sent and the response stream is closed.¶
NOTE: Since caching is meaningless in the context of notifications, this specifications repurposes the deprecated
Expires
header field as an event field to specify when the notifications response ends.¶ -
-
-
SHOULD include the following header fields in the response:¶
-
Vary
([HTTP], Section 12.5.5) which MUST include the following values:¶-
Last-Event-ID
, if the request for PREP notifications included theLast-Event-ID
header field that was not ignored by the resource server.¶
-
Last-Modified
([HTTP], Section 8.8.2).¶
-
-
MAY include the following header fields in the response:¶
-
Accept-Events
which MUST listprep
as one of the available notification protocols. Associated with theprep
list item, the resource server:¶-
MUST include an
accept
event field with at least one acceptable media-type for notifications.¶
-
-
9.2. Body
A resource server sending PREP Notifications MUST transmit a multipart message body ([RFC2046], Section 5.1) with a media type of multipart/mixed
([RFC2046], Section 5.1.3) with two body parts in the order specified below:¶
-
Base Response: the message body that would have been sent had notifications not been requested.¶
-
Notifications Response: the multipart response body with body parts containing notifications as defined in Section 9.2.2.¶
9.2.1. Base Response
By default, the Per Resource Events Protocol requires a resource server to transmit the base response body as first body part of multipart response body. This behaviour is desirable in most scenarios as we short-circuit an extra round trip that would otherwise be needed to fetch the current representation of the resource before fetching notifications and eliminates the need to co-ordinate the two responses.¶
9.2.1.1. Opt out
An application client requesting only notifications using the Per Resource Events Protocol needs to explicitly opt out of receiving the base response as described in Section 7, Request.¶
If the request for PREP notifications includes the Last-Event-ID
header field ([SSE], Section 9.2.4) which matches the Event-ID
of the last event on the resource or wildcard character "*", a resource server SHOULD NOT send the content of the base response.¶
The resource server MUST send still the first body part of the multipart response body, even if this part is empty. The resource server MAY send the headers corresponding to the representation body that would have been sent in the base response, and only omit the representation body of base response.¶
9.2.2. Notifications
A resource server MUST transmit PREP notifications in the second body part of the multipart response as yet another embedded multipart message body ([RFC2046], Section 5.1), with a media type of multipart/digest
([RFC2046], Section 5.1.5) that MAY include zero or more body parts. Each body part of the notifications multipart message body MAY contain at most one notification.¶
9.3. Termination
A resource server MUST end the notification response in any one of the following scenarios:¶
-
Once the time specified in the
expires
parameter of theEvents
header field has elapsed.¶ -
Immediately after sending a notification upon a
DELETE
request on the resource that results in a response with200 (OK)
([HTTP], Section 15.3.1) or204 (No Content)
([HTTP], Section 15.3.5) status codes.¶
A resource server MUST properly terminate the multipart responses as defined in [RFC2046], Section 5.1.2, before closing the response stream.¶
10. Semantics for message/rfc822
notifications
The multipart/digest
multipart media-type ([RFC2046], Section 5.1.5) uses message/rfc822
media-type ([RFC2046], Section 5.2.1) for body parts as default. It follows that the Per Resource Events Protocol transmits notifications as message/rfc822
, unless the application client requests otherwise.¶
10.1. Request
An application clients MAY specify additional parameters to message/rfc822
notification media-type in the accept
event field associated with the prep
list item in the Accept-Events
header field of the request.¶
10.2. Notification
A resource server implementing the Per Resource Events Protocol SHOULD send a notification to an application client when a request with one of the following methods generates a response with any of the following status codes:¶
Request Method | Response Status |
---|---|
PUT ([HTTP], Section 9.3.4) |
200 (OK) ([HTTP], Section 15.3.1) |
PATCH ([RFC5789]) |
204 (No Content) ([HTTP], Section 15.3.5) |
DELETE ([HTTP], Section 9.3.5) |
|
POST ([HTTP], Section 9.3.3) |
200 (OK) ([HTTP], Section 15.3.1) |
204 (No Content) ([HTTP], Section 15.3.5) |
|
201 (Created) ([HTTP], Section 15.3.2) |
|
205 (Reset Content) ([HTTP], Section 15.3.6) |
The notification MUST NOT be sent before the success response has been sent to the user agent that initiated the request.¶
10.3. Headers
A resource server MUST include the following header fields in a message/rfc822
formatted PREP notification:¶
Method
-
identical to
:method
pseudo-header field in a HTTP/2 request ([HTTP/2], Section 8.3.1), that specifies the request method that triggered the notification.¶ Date
-
identical to
Date
header field in a HTTP response ([HTTP], Section 6.6.1), that specifies date and time at which the event that triggered the notification was completed.¶ Event-ID
-
an opaque identifier for the generated notification.¶
A resource server SHOULD include the following headers in a message/rfc822
formatted PREP notification when the state of the resource or its representation is modified as a result of the event:¶
ETag
-
identical to
ETag
header field ([HTTP], Section 8.8.3) in a HTTP response. TheETag
sent MUST be for the sameContent-Type
as the representation that was sent in the notification response or that would have been sent in the absense of theLast-Events-ID
header.¶
A resource server MUST include the following headers in a message/rfc822
formatted PREP notification when a request modifies another resource:¶
Content-Location
-
identical to the
Content-Location
header field ([HTTP], Section 8.7).¶
10.4. Body
The body of a message/rfc822
formatted PREP notification might be used to provide a delta representation, the difference between the state of the representation before and after the most recent event on the resource.¶
If the application client does not specify delta
parameter associated with a preferred notifications format of message/rfc822
in the accept
event field of the request (Section 7) that results in message/rfc822
formatted PREP notifications, the notifications MUST NOT contain a body.¶
If state of the resource is not modified as a result of an HTTP operation, the resulting notification MUST NOT contain a body.¶
If the application client specifies a delta
parameter associated with a preferred notifications format of message/rfc822
in the accept
event field of the request (Section 7) that results in message/rfc822
formatted PREP notifications, a resource server:¶
-
SHOULD send the delta representation as the body of the notification generated upon a
PATCH
([RFC5789]) operation.¶ -
MAY send the delta representation as the body of the notification generated upon a
PUT
([HTTP], Section 9.3.4) or aPOST
([HTTP], Section 9.3.3) operation.¶
A resource server SHOULD send the delta representation in the content-type preferred by the client as specified by the delta
parameter.¶
11. Implementation Guidance
A Connect/Express style middleware for parsing the Accept-Events
header field is available at https://github.com/CxRes/express-accept-events/ and can be installed from npm as express-accept-events
. Complementing this is a Connect/Express style middleware that negotiates an appropriate notifications protocol on the resource based on the request made using the Accept-Event
header field, available at https://github.com/CxRes/express-negotiate-events/ and can be installed from npm as express-negotiate-events
.¶
An early implementation of the Per Resource Events Protocol, also in the form of a Connect/Express style middleware, is available at https://github.com/CxRes/express-prep/ and can be installed from npm as express-prep
.¶
Express Accept Events, Express Negotiate Events and Express PREP are Free and Open Source Software, released under the Mozilla Public License v2.0.¶
The W3C Solid Community Group is developing a specification called Solid-PREP that defines representation and semantics for PREP notifications sent from LDP Resources hosted on Solid storage. This specification enables Solid servers to incorporate the Per Resource Events as a means for sending notifications. Solid-PREP is available at https://github.com/solid/solid-prep/ and is released under the W3C Software and Document license - version 2023.¶
The Node Solid Server, an open source server that implements the Solid Protocol, is in the process of implementing notifications using the Per Resource Events Protocol and Solid-PREP at https://github.com/nodeSolidServer/node-solid-server/tree/prep.¶
The PREP Fetch https://github.com/CxRes/prep-fetch/ library provides a convinient way to consume fetch [FETCH] respsones containing PREP notification. PREP Fetch itself is a thin wrapper on top of Multipart Fetch https://github.com/CxRes/multipart-fetch/ that streams the parts of a multipart response as a series of Fetch Responses.¶
PREP Fetch and Multipart Fetch are Free and Open Source Software, released under the Mozilla Public License v2.0.¶
12. Security Considerations
Since the Per Resource Events Protocol uses HTTP to transmit notifications, it follows that the security and privacy considerations that apply to HTTP also apply to PREP. Considerations relevant to HTTP semantics and its use for transferring information over the Internet are discussed in Section 17 of [HTTP], and considerations related to HTTP/1.1 message syntax and parsing are discussed in Section 11 of [HTTP/1.1].¶
The following is a non-exhaustive list of security and privacy considerations that become especially pertinent due to the manner in which PREP uses HTTP for transmitting notifications:¶
12.1. Browser Fingerprinting
The Accept-Events
header field provides an extra vector that can aid unique identification of user agent. Follow the advice in [HTTP], Section 17.13 to minimize the risk of fingerprinting.¶
12.2. Denial-of-Service Attacks
Resources that serve notifications, by virtue of keeping the response stream open for an extended period of time are more susceptible to Denial-of-Service attacks because the effort required to request notifications from the same resource is tiny compared to the time, memory, and bandwidth consumed by attempting to serve the notifications. Servers ought to ignore, coalesce, or reject egregious notification request, such as repeated notification requests to resource from the same origin.¶
13. IANA Considerations
The change controller for the following registrations is: "IETF (iesg@ietf.org) - Internet Engineering Task Force".¶
13.1. Header Field Registration
IANA has registered the following entry in the "Hypertext Transfer Protocol (HTTP) Field Name Registry" defined by [HTTP]:¶
Header Field Names | Status | Reference |
---|---|---|
Accept-Events
|
Provisional | Section 4 |
Events
|
Provisional | Section 4 |
13.2. Notifications Protocol Registry
The Accept-Events
and Events
header fields identify specific protocols for notifications. The "HTTP Notifications Protocol Registry", created and maintained by IANA at https://www.iana.org/assignments/http-parameters/, registers identifiers for notification protocols.¶
Notifications protocol registrations MUST include the following fields:¶
Initial registrations are given below:¶
Identifier | Name | Reference |
---|---|---|
PREP | Per Resource Events Protocol | This document |
Values to be added to this namespace require IETF Review (see [RFC8126], Section 4.8). Identified protocols MUST conform to the purpose of sending notifications as defined in Section 4 of this document.¶
14. References
14.1. Normative References
- [Delta]
- Mogul, J., Krishnamurthy, B., Douglis, F., Feldmann, A., Goland, Y., van Hoff, A., and D. Hellerstein, "Delta encoding in HTTP", RFC 3229, DOI 10.17487/RFC3229, , <https://www.rfc-editor.org/rfc/rfc3229>.
- [HTTP]
- Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, , <https://www.rfc-editor.org/rfc/rfc9110>.
- [HTTP-Retrofit]
- Nottingham, M., "Retrofit Structured Fields for HTTP", Work in Progress, Internet-Draft, draft-ietf-httpbis-retrofit-06, , <https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-retrofit-06>.
- [HTTP-SF]
- Nottingham, M. and P. Kamp, "Structured Field Values for HTTP", Work in Progress, Internet-Draft, draft-ietf-httpbis-sfbis-06, , <https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-sfbis-06>.
- [HTTP/1.1]
- Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP/1.1", STD 99, RFC 9112, DOI 10.17487/RFC9112, , <https://www.rfc-editor.org/rfc/rfc9112>.
- [HTTP/2]
- Thomson, M., Ed. and C. Benfield, Ed., "HTTP/2", RFC 9113, DOI 10.17487/RFC9113, , <https://www.rfc-editor.org/rfc/rfc9113>.
- [RFC2046]
- Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types", RFC 2046, DOI 10.17487/RFC2046, , <https://www.rfc-editor.org/rfc/rfc2046>.
- [RFC2119]
- Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/rfc/rfc2119>.
- [RFC5789]
- Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 5789, DOI 10.17487/RFC5789, , <https://www.rfc-editor.org/rfc/rfc5789>.
- [RFC8126]
- Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, , <https://www.rfc-editor.org/rfc/rfc8126>.
- [RFC8174]
- Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/rfc/rfc8174>.
- [SSE]
- "Server-Sent Events", W3C REC eventsource, W3C eventsource, <https://www.w3.org/TR/eventsource/>.
14.2. Informative References
- [FETCH]
- "Fetch - Living Standard", <https://fetch.spec.whatwg.org>.
- [REST]
- Fielding, R. T., "Architectural Styles and the Design of Network-based Software Architectures", Doctoral Dissertation, University of California, Irvine, <https://roy.gbiv.com/pubs/dissertation/top.htm>.
- [RFC7838]
- Nottingham, M., McManus, P., and J. Reschke, "HTTP Alternative Services", RFC 7838, DOI 10.17487/RFC7838, , <https://www.rfc-editor.org/rfc/rfc7838>.
- [RFC9205]
- Nottingham, M., "Building Protocols with HTTP", BCP 56, RFC 9205, DOI 10.17487/RFC9205, , <https://www.rfc-editor.org/rfc/rfc9205>.
- [WEBSUB]
- "WebSub", W3C REC websub, W3C websub, <https://www.w3.org/TR/websub/>.
- [WS]
- "The WebSocket API", W3C NOTE websockets, W3C websockets, <https://www.w3.org/TR/websockets/>.
Index
-
-
- Accept-Events
-
Section 1.2.2, Paragraph 1; Section 1.2.2, Paragraph 3; Section 1.2.3, Paragraph 1; Section 1.2.4.1, Paragraph 1; Section 1.2.4.3, Paragraph 2; Section 3.5, Paragraph 2.6.1; Section 4.1; Section 4.2, Paragraph 2; Section 4.2, Paragraph 3; Section 4.2.1, Paragraph 1; Section 5.1, Paragraph 2; Section 5.2, Paragraph 2; Section 5.2, Paragraph 4; Section 5.3, Paragraph 2; Section 6.2, Paragraph 1; Section 6.3, Paragraph 1; Section 7, Paragraph 3.1.1; Section 7, Paragraph 6; Section 8.1, Paragraph 3.1.1; Section 9.1, Paragraph 2.2.2.1.2.1.1; Section 9.1, Paragraph 2.3.2.1.1; Section 10.1, Paragraph 1; Section 12.1, Paragraph 1; Table 2; Section 13.2, Paragraph 1¶
- application client
-
Section 3.4, Paragraph 2.2.1; Section 3.5, Paragraph 2.2.1; Section 4.1, Paragraph 1; Section 4.1, Paragraph 3; Section 4.1, Paragraph 4; Section 5.2, Paragraph 4; Section 6, Paragraph 1; Section 6.1, Paragraph 1; Section 7, Paragraph 1; Section 7, Paragraph 2; Section 7, Paragraph 3.1.2.1.2.1.1; Section 8.3, Paragraph 1; Section 9.2.1.1, Paragraph 1; Section 9.2.2, Paragraph 2.2; Section 9.3, Paragraph 4.2; Section 10, Paragraph 1; Section 10.1, Paragraph 1; Section 10.2, Paragraph 1; Section 10.4, Paragraph 2; Section 10.4, Paragraph 4¶
-
-
-
- event field
-
Section 4.2, Paragraph 1; Section 5.1, Paragraph 1; Section 5.1, Paragraph 3.1.1; Section 5.1, Paragraph 3.2.1; Section 5.1, Paragraph 3.3.1; Section 6.3, Paragraph 2; Section 7, Paragraph 3.1.2.1.2.1.1; Section 7, Paragraph 6; Section 8.1, Paragraph 3.2.1; Section 8.2, Paragraph 4.1.2.1.1; Section 8.2, Paragraph 4.1.2.2.1; Section 8.3, Paragraph 3.1.2.1.1; Section 8.3, Paragraph 3.1.2.2.1; Section 9.1, Paragraph 2.1.2.3.1; Section 9.1, Paragraph 2.1.2.3.3; Section 9.1, Paragraph 2.3.2.1.2.1.1; Section 10.1, Paragraph 1; Section 10.4, Paragraph 2; Section 10.4, Paragraph 4¶
- Events
-
Section 1.2.4.1, Paragraph 1; Section 3.5, Paragraph 2.6.1; Section 4.2; Section 5.1, Paragraph 2; Section 5.2, Paragraph 5; Section 5.2, Paragraph 6; Section 5.3, Paragraph 2; Section 5.3, Paragraph 3; Section 8.1, Paragraph 3.2.1; Section 8.2, Paragraph 4.1.1; Section 8.3, Paragraph 3.1.1; Section 9.1, Paragraph 2.1.2.3.1; Section 9.3, Paragraph 2.1.1; Table 2; Section 13.2, Paragraph 1¶
-
-
-
- notification
-
Section Abstract, Paragraph 1; Section 1, Paragraph 1; Section 1.1, Paragraph 3; Section 1.2.2, Paragraph 1; Section 1.2.2, Paragraph 3; Section 1.2.4, Paragraph 1; Section 1.2.4.1, Paragraph 1; Section 1.2.4.3, Paragraph 1; Section 1.2.4.3, Paragraph 2; Section 1.2.4.3, Paragraph 3; Section 1.2.4.4, Paragraph 1; Section 1.3, Paragraph 2.1.1; Section 1.3, Paragraph 2.2.1; Section 1.3, Paragraph 2.3.1; Section 1.3, Paragraph 2.4.1; Section 1.3, Paragraph 4.2.1; Section 1.3, Paragraph 4.2.2.1.1; Section 1.3, Paragraph 4.2.2.2.1; Section 2, Paragraph 1; Section 2, Paragraph 2; Section 2, Paragraph 3; Section 2.1, Paragraph 1; Section 2.2, Paragraph 2.1.1; Section 2.2, Paragraph 2.2.1; Section 2.2, Paragraph 2.3.1; Section 2.3, Paragraph 2.2.1; Section 2.4, Paragraph 1; Section 2.4, Paragraph 2; Section 3.5; Section 3.5, Paragraph 2.4.1; Section 4, Paragraph 1; Section 4.1, Paragraph 1; Section 4.1, Paragraph 2; Section 4.1, Paragraph 3; Section 4.1, Paragraph 4; Section 4.1.1, Paragraph 1; Section 4.1.1, Paragraph 2; Section 4.1.2, Paragraph 1; Section 4.1.2, Paragraph 2; Section 4.1.2, Paragraph 3; Section 4.2, Paragraph 1; Section 4.2.2, Paragraph 1; Section 5.1, Paragraph 1; Section 5.2, Paragraph 1; Section 5.2, Paragraph 3; Section 5.3, Paragraph 1; Section 5.3, Paragraph 2; Section 5.3, Paragraph 3; Section 6, Paragraph 1; Section 6.1, Paragraph 1; Section 6.2, Paragraph 1; Section 6.3, Paragraph 1; Section 6.3, Paragraph 2; Section 7, Paragraph 1; Section 7, Paragraph 2; Section 7, Paragraph 3.1.2.1.1; Section 7, Paragraph 3.1.2.1.2.1.1; Section 7, Paragraph 3.2.1; Section 7, Paragraph 6; Section 8.1, Paragraph 1; Section 8.1, Paragraph 2; Section 8.1, Paragraph 4.2; Section 8.2, Paragraph 1; Section 8.2, Paragraph 3; Section 8.3, Paragraph 1; Section 8.3, Paragraph 2; Section 8.3, Paragraph 3.1.2.2.1; Section 9.1, Paragraph 1; Section 9.1, Paragraph 2.1.2.3.2.3.1; Section 9.1, Paragraph 2.1.2.3.3; Section 9.1, Paragraph 2.2.2.1.2.2.1; Section 9.1, Paragraph 2.3.2.1.1; Section 9.1, Paragraph 2.3.2.1.2.1.1; Section 9.2, Paragraph 1; Section 9.2, Paragraph 2.1.1; Section 9.2, Paragraph 2.2.1; Section 9.2.1, Paragraph 1; Section 9.2.1.1, Paragraph 1; Section 9.2.1.1, Paragraph 2; Section 9.2.2, Paragraph 1; Section 9.2.2, Paragraph 2.2; Section 9.3, Paragraph 1; Section 9.3, Paragraph 2.2.1; Section 9.3, Paragraph 4.2; Section 10, Paragraph 1; Section 10.1, Paragraph 1; Section 10.2, Paragraph 1; Section 10.2, Paragraph 3; Section 10.3, Paragraph 1; Section 10.3, Paragraph 2.2.1; Section 10.3, Paragraph 2.4.1; Section 10.3, Paragraph 2.6.1; Section 10.3, Paragraph 3; Section 10.3, Paragraph 4.2.1; Section 10.3, Paragraph 6; Section 10.4, Paragraph 1; Section 10.4, Paragraph 2; Section 10.4, Paragraph 3; Section 10.4, Paragraph 4; Section 10.4, Paragraph 5.1.1; Section 10.4, Paragraph 5.2.1; Section 11, Paragraph 1; Section 11, Paragraph 4; Section 11, Paragraph 5; Section 11, Paragraph 6; Section 12, Paragraph 1; Section 12, Paragraph 2; Section 12.2, Paragraph 1; Section 13.2, Paragraph 1; Section 13.2, Paragraph 2; Section 13.2, Paragraph 6¶
-
-
-
- resource server
-
Section 3.4, Paragraph 2.2.1; Section 4.1, Paragraph 2; Section 4.2, Paragraph 1; Section 4.2, Paragraph 2; Section 4.2, Paragraph 3; Section 5.2, Paragraph 2; Section 5.2, Paragraph 5; Section 5.2, Paragraph 6; Section 5.3, Paragraph 2; Section 6, Paragraph 1; Section 6.1, Paragraph 1; Section 6.2, Paragraph 1; Section 6.3, Paragraph 1; Section 6.3, Paragraph 2; Section 6.3, Paragraph 4.2; Section 6.3, Paragraph 4.3; Section 7, Paragraph 2; Section 7, Paragraph 3.2.1; Section 7, Paragraph 4.2; Section 7, Paragraph 6; Section 8.1, Paragraph 1; Section 8.1, Paragraph 2; Section 8.1, Paragraph 4.2; Section 8.2, Paragraph 1; Section 8.2, Paragraph 3; Section 8.3, Paragraph 1; Section 8.3, Paragraph 2; Section 9.1, Paragraph 1; Section 9.1, Paragraph 2.2.2.1.2.2.1; Section 9.1, Paragraph 2.3.2.1.1; Section 9.2, Paragraph 1; Section 9.2.1, Paragraph 1; Section 9.2.1.1, Paragraph 2; Section 9.2.1.1, Paragraph 3; Section 9.2.2, Paragraph 1; Section 9.2.2, Paragraph 2.2; Section 9.3, Paragraph 1; Section 9.3, Paragraph 3; Section 10.2, Paragraph 1; Section 10.3, Paragraph 1; Section 10.3, Paragraph 3; Section 10.3, Paragraph 6; Section 10.4, Paragraph 4; Section 10.4, Paragraph 6¶
-