diff --git a/inbox/pubsub-caching-hints.xml b/inbox/pubsub-caching-hints.xml new file mode 100644 index 00000000..9cc40338 --- /dev/null +++ b/inbox/pubsub-caching-hints.xml @@ -0,0 +1,318 @@ + + +%ents; +]> + + +
+ Pubsub Caching Hints + This specification provides a way to get caching information from a Pubsub node + &LEGALNOTICE; + xxxx + ProtoXEP + Standards Track + Standards + Council + + XMPP Core + XEP-0060 + + + + pubsub-caching + + Jérôme + Poisson + goffi@goffi.org + goffi@jabber.fr + + + 0.0.1 + 2021-07-19 + jp +

First draft.

 + +
+ +

XMPP Pubsub as described in &xep0060; is a very powerful and versatile tool, which is used for numerous XMPP features. For many reasons, notably speed improvement and resources optimisation, XMPP clients may want to cache internally Pubsub nodes and keep cache synchronised with cached pubsub service. Unfortunately the flexibility of Pubsub makes the choice of a good caching strategy complicated and non optimal. This XEP standardize a way for the Pubsub service to give extra information to fix this situation.

+ + +

Caching information must be using base XEP-0060 Pubsub features and be easy to obtain for the client, and easy to add for the pubsub service. The desired goals are:

+ + + + + + + +

Pubsub Caching Hints are using the Pubsub node metadata as described in Discover Node Metadata section of &xep0060;

+

Hints are advertised using well known fields in Pubsub metadata disco extension. If a Pubsub service implements this XEP, and if it also manages a &xep0163; service, the fields described here MUST be present for both Pubsub and PEP nodes.

+ + + + +

To properly cache a node, a client must known if they are kept in storage or not. To advertise that fact, a Pubsub node compliant with this standard MUST use a field named {urn:xmpp:pubsub-caching:0}persistence of type list-single and whose value can be one of:

+ + + + +

It may be necessary to cache a node, to know how many items the Pubsub Service is keeping before silently deleting them, or when they do expire. This is done by advertising it using the pubsub#max_items and pubsub#item_expire fields of type integer-or-max (this type is defined in XEP-0060).

+

Both fields are mentioned in XEP-0060, but as a reminder:

+ + + + + +

Pubsub is most often used to let allowed users store and retrieve unmodified items. However, nothing in &xep0060; prevents a Pubsub service to return dynamic items with identical IDs depending on factors like the JID of the requestor, time of the day, or something else. For instance, a weather service could return local prevision for following day using item identifier like "tomorrow_forecast", or a machine learning algorithm could return favorite Shakespeare books to a user using "favorite" item id, in which case romeo@montaigu.lit would probably have different results than juliet@capulet.lit

+

For obvious reason those items are hard to impossible to cache. Pubsub services SHOULD avoid using dynamic items, unless there is a really good reason for it.

+

If a Pubsub service implements Caching Hints and if items are static (i.e. items with the same ID are identical whatever user is requesting them, time of day it is, or any other variable parameter), then it MUST advertise this fact by using the field named {urn:xmpp:pubsub-caching:0}consistent-items of type boolean with the value of true.

+ +

Note that overwriting an items as specified in XEP-0060 Publish an Item to a Node is a normal Pubsub use case which SHOULD result in proper notifications being sent to subscribers, if the item is not otherwise different, this is considered as static item and MUST result in a value of true for the {urn:xmpp:pubsub-caching:0}consistent-items field.

+ +

Respectively, if a Pubsub node delivers one or more dynamic items, it MUST avertise the fact by using the value of false for the same field.

+ + + + +

A Pubsub service may have a feature to restrict individual items from a node to some entities (e.g. to have some items only visible to family, friends or coworkers). In this case, we say that the node has inconsistent items set, and this implies that cache must not be shared between users (as some users may have access to some items that other don't).

+

If a Pubsub node is always returning the same items ids to all allowed users, it MUST advertise this fact by using the value true for the boolean field {urn:xmpp:pubsub-caching:0}consistent-set.

+ +

On the other hand, if a Pubsub node may return different items according to the requesting entities (assuming that entities are allowed at the node level), it MUST advertise this fact by using the value false for the same field.

+ + + +

Normally, items are managed like a queue in a node, i.e. new items are appended to one ends, and existing items can only be deleted (or overwritten, in which case an item with the same ID is appended to the end). However, it may be necessary for a Pubsub service to include items out of order (i.e. not appending it at the end), for instance when a Pubsub service is a bridge to a third party protocol which receives items out of order.

+

Unstable items doesn't change the fact that node can be shared between users or node, but it may have an impact on client implementation, as the caching implementation may have items in a different order, and items may be missed, thus this fact is valuable to know for a client willing to cache the node. Note that unstable items SHOULD be avoided by a Pubsub service whenever it's possible.

+

If items are always appended to the end of the queue, the Pubsub node MUST advertise this fact using the {urn:xmpp:pubsub-caching:0}stable-items field of type boolean with a value of true.

+

On the other hand, if items order can't be guaranteed, the Pubsub node MUST advertise this fact by using the value of false for the same field

+ + + +

To synchronize correctly a Pubsub node, an XMPP client must be aware of any modification that happen to its items or to the node itself. This is possible thanks to the subscription mechanism of &xep0060;. However, notification can be skipped, notably item retraction notification must be explicitly requested by the client, and thus may be missing, resulting in cache becoming out of sync with the Pubsub service

+

To avoid that, the Pubsub service may enforce notifications for all modifying events to a node or its items, even if they are not explicitly requested by the user doing the modification.

+

If a node always sends notification, including <retact> notifications even if notify attribute is not set, then it must advertise this fact using the field named {urn:xmpp:pubsub-caching:0}alway-notify of type boolean with the value of true. If notifications may be omitted, then the same field must be used with the value of false.

+

A Pubsub service allowing a node to have notifications always sent SHOULD allow the node owners to activate or deactivate this feature through node configuration, using the well-known field with the same name of {urn:xmpp:pubsub-caching:0}always-notify and the same type of boolean. It's up to the implementation to determine if the default value should be true or false.

+ + + +

If the node is public, i.e. if it as an open access model that means that a client can safely share the cache between users (providing that the consistent items and consistent set fields are also both true).

+

If a Pubsub node is public, it MUST advertise this fact by exposing it in its metadata using the field named pubsub#access_model of type list-single with a value of open

+

If the node has an other access model, it is up to the Pubsub implementation to advertise publicly or not this data in the node metadata. It may be a privacy concern to expose any other access model than open

+ + + +

An XMPP client may have a feature to suggest new Pubsub nodes to users (for network exploration, and let users find rapidly interesting content). If the discovery feature is not restricted to some users somehow, this SHOULD be done using only public nodes. But even for a public node, the node owner may no be willing to have they node suggested to random users.

+

To avoid using inappropriately a public node for suggestion, a Pubsub node MUST announce if the node is usable for suggestion or node by using the field named {urn:xmpp:pubsub-caching:0}allowed-for-suggestions of type boolean. It is up to the Pubsub implementation to decide how this field is set, but it SHOULD have a default value of false and it should be modifiable by node owner through node configuration, using the well-known field with the same name of {urn:xmpp:pubsub-caching:0}allowed-for-suggestions and the same type of boolean.

+

A client MUST NOT use a node with {urn:xmpp:pubsub-caching:0}allowed-for-suggestions set to false for suggestions

+ + + +

&xep0060; wording about purging all node items is not clear about the last item, and it may or may not be kept.

+

To make it explicit, a client implementing this specification MUST use the field named {urn:xmpp:pubsub-caching:0}purge-keep-last-item of type boolean with the value of true if the last item is NOT retracted when a node purge is performed. On the opposite, the value of true MUST be used if ALL items are retracted when a node purge is performed, actually leaving the node empty, with no item at all.

+ + + +

Here a is a table summarizing all fields to announce when implementing this XEP. All fields but pubsub#access_model are mandatory if a Pubsub service advertise support for this XEP.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
namefieldtypemeaningcomment
Max Itemspubsub#max_itemsinteger-or-maxHow many items are kept in storage
Item Expirepubsub#item_expireinteger-or-maxHow many seconds items are kept
Node Persistence{urn:xmpp:pubsub-caching:0}persistencelist-singleItems are kept in persistent storage
Consistent Items{urn:xmpp:pubsub-caching:0}consistent-itemsbooleanItems are static
Consistent Set{urn:xmpp:pubsub-caching:0}consistent-setbooleanAll users have the same items
Stable Items{urn:xmpp:pubsub-caching:0}stable-itemsbooleanItems are not added out of order
Always Notify{urn:xmpp:pubsub-caching:0}always-notifybooleanModifying Notifications are Always sent to subscribers, even if not explicitly requested by publisher.
Public Nodepubsub#access_modellist-singleItems can be retrieved by anybodyif value is not open, it may be omitted
Allowed for Suggestions{urn:xmpp:pubsub-caching:0}allowed-for-suggestionsbooleanNode and its items can be suggested to random usersSHOULD be settable by node owner, and MUST default to false
Purge Keep Last Item{urn:xmpp:pubsub-caching:0}purge-keep-last-itembooleanLast item is always kept when a node purge is performed
+ + + +

Here is an example of Pubsub metadata advertised by a node on a service implementing this XEP. This example is a "happy path", i.e. features announced here are cache friendly.

+ + + +]]> + + + + + + + Princely Musings (Atom) + + + max + + + max + + + persistent + + + true + + + true + + + true + + + true + + + open + + + true + + + false + + + + + ]]> + + + +

If a server supports the "Pubsub Caching Hints" protocol, it must advertize it by including the "urn:xmpp:pubsub-caching:0" discovery feature &NSNOTE; in response to a &xep0030; information request:

+ + + +]]> + + + … + + … + + +]]> + + + +

As order of insertion and overwriting of items may be relevant to the client, it is recommended for caching-friendly Pubsub service to implement &xep0413;, thus client can cache items using an order by date of creation.

+ + +

TODO

+ + +

TODO

+ + +

TODO

+ + +

TODO

+ +