The editor requested renaming the spec for something friendlier to non-English speakers. Group generally agreed.

Please bikeshed.

In the event of an error, hubs should return a description of the error in the response body as plain text.

Similar to Micropub #36, this will get flagged by the i18n review. The solution we arrived at with Micropub was to clarify that this message is intended for the developer, and not intended to be user visible. This way we can avoid the need for handling text direction and localization of the string.

In the event of an error, hubs should return a description of the error in the response body as plain text, used to assist the client developer in understanding the error. This is not meant to be shown to the end user.

In the draft of 20 Oct 2016, section 6 says

The request MUST include a Link Header [RFC5988] with rel=hub pointing to the Hub as well as a Link Header [RFC5988] with rel=self set to the topic that's being updated.

I have two questions:

1. Which hub is to be denoted in the rel=hub link?
   1. The local hub, the one immediately issuing this particular notification
   2. The upstream-most hub, the one advertised by the topic resource itself during discovery
2. Which resource is to be denoted in the rel=self link?
   1. The topic url as supplied in the subscription request
   2. The rel=self from discovery, if there was one, falling back if not to the topic url supplied in the subscription request

My guess is 1.(i) and 2.(i).

• SHOULD use capability URLs with a large enough entropy to not be guessable
• SHOULD generate a new unique URL the subscriber renews the subscription
• the hub MUST enforce lease expirations, and more than 3 months is a warning in the test tool

Now that the rename is complete, and a new draft is up (yay!), https://www.w3.org/TR/pubsub/ should redirect to https://www.w3.org/TR/websub/.

In the 20 Oct draft, I see "This request has a Content-Type of application/x-www-form-urlencoded". I had overlooked this when building my implementation, which led to failures in interop testing with pubsub.rocks.

In fact, my first reading of the sentence in the spec is that it tells me how to format the body, but doesn't directly tell me anything about whether or which Content-Type header I should or must include. Perhaps strengthening this to a SHOULD or a MUST would help.

Concretely, I suggest revising the opening lines of the "Subscriber Sends Subscription Request" section to be:

Subscription is initiated by the subscriber making an HTTPS or HTTP POST [[!RFC7231]] request to the hub URL. This request MUST have a Content-Type header of application/x-www-form-urlencoded (described in Section 17.13.4 of [[!W3C.REC-html401-19991224]]) and the following parameters in its body, formatted accordingly:

hub.secret is available (when supplied in a subscription request) for use in subscription denial notifications and in verification of intent requests. Should it be used to authenticate the message from the hub in these circumstances? It could take the form of an X-Hub-Signature header on these requests just like for authenticated content distribution. The scope of the signature would be the hub.* parameters, presumably.

Ask @rhiaro for the right stuff to put in there.

The specification of 20 Oct 2016 specifies hub.lease_seconds as specifying a finite number of seconds after which a subscription will expire.

Previous PSHB discussion [1] included discussion of a special value indicating a lease of unbounded duration, for use both in requests from subscribing parties and verifications from hubs. Suggestions for a concrete value included 0 and -1; I'd also like to suggest unbounded here. I also recommend that 0 not be considered as an indication of unboundedness, since it already has a reasonable meaning when interpreted as an actual lease duration.

Having an explicit value would help avoid situations where 'random large integers' like 999999 etc. are used in place of a true unbounded value.

[1] e.g. https://groups.google.com/forum/#!msg/pubsubhubbub/q6_ahhn1FpU/uXW8d58BKAkJ

The discovery section states:

The former MUST indicate the exact URL of a WebSub hub designated by the publisher

What does "exact" mean in this case? Does it mean "absolute" or "full"?

Note that the web linking rfc allows relative URLs https://tools.ietf.org/html/rfc5988#section-5.1

If the URI-Reference is relative, parsers MUST resolve it

Here's how I did it in Micropub: https://github.com/w3c/Micropub/blob/master/draft/source/index.html#L18

https://pubsub.rocks/

The hub as specified in the draft of 20 Oct 2016 can delete a subscription unilaterally from time to time:

• when a lease expires
• (perhaps) when a content distribution attempt fails "often enough" (see issue #15)
• (perhaps) in other situations?

It may be worth considering sending a notification of unsubscription when any of these events occur.

Such a notification could be similar to an unsubscription verification, except that the response from the subscriber would be ignored (and hub.challenge would be omitted, etc).

Would it be okay, to add custom metadata to the Link headers as target attributes?
For example during discovery:

Link: <http://example.org>; rel="self"; title="example",
	<http://example.org/hub>; rel="hub"; title="example hub"

We are trying to solve the problem, that our publishers have only the possibility to compare IRIs by Simple String Comparison [¹], so the the topic urls http://über.com and http://%C3%BCber.com would be two different for them.

But according to that according to [RFC5988], Section 5.1 the topic IRI http://über.com needs to be transcribed as http://%C3%BCber.com in the Link Header (e.g. Link: <http://%C3%BCber.com>; rel="self").

The subscriber cannot differentiate between the escaped and the unescaped topics.
We would like to extend the topic link header with the target attribute (encoded="false"), so that:

1. http://über.com maps to: Link: <http://%C3%BCber.com>; rel="self"; encoded="true" or Link: <http://%C3%BCber.com>; rel="self"
   Example Subscription Request:

   POST /hub HTTP/1.1
   Content-Type: application/x-www-form-urlencoded; charset=utf-8
   Host: example.org
   Connection: close
   Content-Length: 118
   
   hub.callback=http%3A%2F%2Fexample.org%2Fsubscriber%2Fcb%2F1234&hub.mode=subscribe&hub.topic=http%3A%2F%2F%C3%BCber.com
   

2. http://%C3%BCber.com maps to: Link: <http://%C3%BCber.com>; rel="self"; encoded="false"
   Example Subscription Request:

   POST /hub HTTP/1.1
   Content-Type: application/x-www-form-urlencoded; charset=utf-8
   Host: example.org
   Connection: close
   Content-Length: 122
   
   hub.callback=http%3A%2F%2Fexample.org%2Fsubscriber%2Fcb%2F1234&hub.mode=subscribe&hub.topic=http%3A%2F%2F%25C3%25BCber.com
   

Do you think this is a valid solution to our problem? If you want, I can go into details why our publishers compare IRIs only by Simple String Comparison.

/cc @depressiveRobot

[^1]: [[RFC 3987], 5.3.1. Simple String Comparison]¹

From section 4.2 of the spec:

If (and when), the subscription is denied, the hub MUST inform the subscriber by sending an HTTP [RFC7231] GET request to the subscriber's callback URL as given in the subscription request.

GET requests are typically intended to be used to fetch documents--notifications such as this are generally done with POST.

Encoding the arguments in a query string seems a bit inelegant compared to just using the POST forms we're all used to--least of all because topics and reasons might result in a large and/or malformed URL.

i am woondering if this has been implemented, and if so, how robust it is: "The hub MAY reduce the payload to a diff between two consecutive versions if its format allows it."
even if we assume that a hub never misses a topic update, the same cannot be said for subscribers, so for them getting diffs may be problematic. they might also not even notice that there is a problem, unless the versions carry ETags strong enough to verify the versions, and their ability to be used for diff purposes.

if <a rel="hub"> is allowed, then people could hijack the page's hub URL via the HTML comments box. " together with fat pings this would mean that I could inject fake news into people's readers when they susbcribe to someone's blog, just by posting a comment with a rel=hub link"

Please also note in the security considerations why implementations MUST NOT support <a rel="hub">

The specification does not state the cardinality of the relationship between topics and hubs. Given that you have to send the topic in the subscribe request, the implication is that it is not one to one, and many topics can share the same hub but that is not stated anywhere (that I can find).

The specification recommends, though still somewhat implicitly, that there be one callback URL per Topic.

This distinction seems inconsistent. If the subscriber (typically less capable than a hub) SHOULD implement multiple callback endpoints, then it seems like the hub SHOULD also do the same? Otherwise, drop the recommendation for the callbacks?

At the end of 4.3.1 is the statement:

Hubs MUST enfore [sic] lease expirations, and MUST NOT issue perpetual lease durations.

This seems overly restrictive and unenforceable. The hub can issue a lease for MAX_INT seconds and be compliant, thereby ignoring the subscriber's request and having a "limited" lease duration that it never needs to expire. This is allowed by:

Hubs MAY make the hub.lease_seconds equal to the value the subscriber passed in their subscription request but MAY change the value depending on the hub's policies.

I suggest simply removing the requirement, making the implementations easier when perpetual leases are desirable.

I am currently writing a subscriber. Section 4.3 describes the verification request that hub sends, where the subscriber is supposed to echo back the challenge.

1. My subscriber requests the subscription from the hub.
2. The hub asynchronously makes a request back to the subscriber to verify the subscription request.
3. I use that request to mark that the subscription was successful. If the hub never makes that verification request, then I know something went wrong and can mark the subscription as not yet active.

The problem lies in that the verification request is a GET request with no secret information, so anybody could forge a verification request to my subscriber. A forged request could also set the lease_seconds to something that could trick the subscriber into thinking things are different.

Potential solutions:

• The hub could include the hub.secret that the subscriber sent in the first place (Probably not a good idea since this is sent in a GET request and secrets in query parameters is generally bad)
• The hub could use the hub.secret to compute a digest of the other query parameters, and pass the digest in the request as well.
• Add a new parameter to the subscription and verification used for this purpose.
• Other thoughts?

In the draft of 20 Oct 2016, section 4.1 says:

Any failures to confirm the subscription action MUST leave the subscription state unchanged.

And section 4.1.2 says:

The hub MUST respond to a subscription request with an HTTP [RFC7231] 202 "Accepted" response to indicate that the request was received and will now be verified (Section 5.3 ) and validated (Section 5.2 ) by the hub. The hub SHOULD perform the verification and validation of intent as soon as possible.

And section 4.2 says:

If (and when), the subscription is accepted, the hub MUST perform the verification of intent of the subscriber.

My questions are:

1. Does "confirmation of the subscription action" include verification of intent?
   1. for the initial subscription?
   2. for subsequent edits/renewals?
2. May the hub answer 202 prior to verification of intent?
3. May the hub verify intent before making a decision about how to respond to a subscription request?
4. If so, if verification fails, must the hub answer 202, or may it answer some other code?
5. If so, what code(s) (and their meanings) would be appropriate for failure to verify intent?

My guesses, based on the spec and intuition, are that the answers are/should be:

1. yes to both
2. yes, but it doesn't have to
3. yes
4. it may answer some other code
5. I'm not sure yet

WebSub requires each resource to be delivered with a rel=self link:

Link Headers [RFC5988]: the publisher SHOULD include at least one Link Header [RFC5988] with rel=hub (a hub link header) as well as exactly one Link Header [RFC5988] with rel=self (the self link header)

The web is already adding links to the resource itself in HTML pages, it's the rel=canonical link which is supported by major search engines since 2009.

I do not see a reason to add a second link that has the same meaning. Please drop rel=self and replace it with rel=canonical.

See https://chat.indieweb.org/2015-05-22#t1432330810734000 for a discussion in die #indieweb channel about this:

tantek: however, this "even if the same resource is served at http, https, /, and /index.html, only one of those URls actually works as the push topic" - is an already solved problem
search engines have the same problem
and previously solved it with rel=canonical
thus if that really is a problem for PuSH as well, the PuSH should build upon the pre-existing rel=canonical for the page, rather than require rel=self

Are there any publicly-available resources for testing interop between hub and subscriber implementations?

Perhaps implementers could provide something offering limited-duration subscriptions to a simple time service that updates once every configurable numbers of seconds.

I'm building an implementation from the current spec and would very much like to see whether it works with others' implementations, and where any points of friction might be.

Add a Conformance Classes section (like Webmention's https://www.w3.org/TR/webmention/#conformance-classes ) with subsections for Publishers, Subscribers, and Hubs explicitly listing the conformance criteria for each.

In the draft of 20 Oct 2016, section 6 includes the text:

The successful response from the subscriber's callback URL MUST be an HTTP [RFC7231] success (2xx) code. The hub MUST consider all other subscriber response codes as failures; that means subscribers MUST NOT use HTTP redirects for moving subscriptions. The response body from the subscriber MUST be ignored by the hub. Hubs SHOULD retry notifications repeatedly until successful (up to some reasonable maximum over a reasonable time period).

What happens when a consistently-failing delivery exceeds the reasonable maximum / reasonable time period?

Proposal: the subscription is terminated/deleted/unsubscribed, and the normal flow of events for a hub-initiated subscription termination is kicked off.

If the subscriber is subscribing the same topic at multiple hubs, there is no way to tell which hub is making the verification request. Section 4.3.1 says that the subscriber MUST confirm that the topic corresponds to a pending subscription. This means if there are two pending subscriptions for the topic (at different hubs), it's ambiguous as to which the verification request corresponds to.

Potential solutions:

• Add a parameter to the verification request where the hub sends its own URL in the request so that the subscriber can match the verification request to its subscription request.

this is a design change issue. what about using a subscription resource? this could make the protocol much more RESTful and also solve some existing issues more elegantly and easily. assuming you POST the subscription request, let's do it like this:

• a subscription resource is created and the resource URI returned
• the Sunset header [1] of the resource says how long it lives (if it expires)
• unsubscriptions DELETE the subscription resource
• servers may support GET of the subscription resource to provide subscription metadata (this is for example how delivery attempts could be signaled, see #15)

[1] http://webconcepts.info/specs/IETF/I-D/wilde-sunset-header

without trying to get into naming fights: if RFC 3986 gets referenced (which is currently the case, and i think that's a good choice), then it would be good to use the terminology of this spec and refer to RFC 3986 identifiers as URIs.

The "Content Distribution" section leaves open the possibility for both fat pings and thing pings, and within fat pings the option of sending the entire document vs sending a diff. (For context, PuSH 0.3 required that the content in the notification was an Atom feed document.)

It would be useful to document the current state of what interoperable implementations are actually doing, in order to provide guidance to people who are using one of the formats in the list.

From my understanding, we have the following combinations of content types and notification types as existing interoperable implementations:

• RSS with thin pings
• Atom with thin pings
• h-entry with thin pings

I could not find any documentation on implementations that support fat pings. I thought Superfeedr sent fat pings, but I can't find the documentation on what it actually sends. Please comment here with a link to documentation of other formats or notification payload types.

Obviously PubSub would work great for subscribing to an ActivityStreams JSON feed, but I don't know of any implementations of that currently. We can add this as an "at risk" feature since it clearly makes sense as a use case but is not implemented yet.

as discussed in today's telcon. cc: @aaronpk

WebSub requires publishers to add a rel=self link to each document:

The discovery mechanism aims at identifying at least 2 URLs.
...
The canonical URL for the topic to which subscribers are expected to use for subscriptions.
The protocol currently supports the following discovery mechanisms. Publishers MUST implement at least one of them:
...

Please drop the MUST requirement for the rel=self URL and let clients fall back to URL that was used to retrieve the document. This will make it easier to implement WebSub on the publisher side.

Also see the discussion in the #indieweb channel: https://chat.indieweb.org/2015-05-22#t1432330396549000

The draft of 20 Oct 2016 includes, in section 6.1.2, the text

Please note however that this signature only ensures that the payload was not forged. Since the notification also includes headers, these should not be considered as safe by the subscriber, unless of course the subscriber uses HTTPS [RFC2818] callbacks.

I don't understand how HTTPS callbacks help the subscriber trust that the headers aren't forged. I imagine that most HTTPS servers (hosting the receive end of a callback) wouldn't validate the identity of a connecting client, and so would be susceptible to replay of previous payloads with altered headers.

Perhaps it would be better to amend the text to read as follows:

Please note however that this signature only ensures that the payload was not forged. Since the notification also includes headers, these should not be considered as safe by the subscriber.

i think it's great that the name was changed form what started as a joke to something that can be pronounced and used. but i think this is another incidence of using "class names" as "instance names" that makes things unnecessarily confusing. PubSub is a well-established name for a class of protocols/mechanisms. hijacking this as a name for one specific one is confusing. after a long and painful experience with "XML Schema", where @w3c decided to call a "XML Schema" language "XML Schema", we have a solid body of evidence that this is a bad idea as a naming strategy. so if possible at all, i'd like to encourage the group to come up with a name that is less confusing to the community, and will make it easier for all of us working with protocols and teaching them to avoid terminology confusion if we can. thank you very much!

I just noticed that the Discovery section says "polling" which seems awkward since the spec is supposed to get around the need for polling.

The latter will point to the permanent URL for the resource being polled. [1]

I'd suggest changing this to something like:

The latter will point to the permanent URL for the resource for which notifications will be sent.

is the list of algorithm names given in https://www.w3.org/TR/pubsub/#recognized-algorithm-names a closed and stable list? if not (and this should be looking forward a few years), maybe it would be a good idea to have a registry for them (with the four listed values as initial contents), so that new names can be added as they may get added by implementations and subsequently should be discoverable through the registry.

It's often said^{citation needed} that protocols absolutely must be versioned. Does that apply here? Would we want something like a "hub.version=..." parameter in (un)subscription requests and in callback invocations?

Especially where there might be small differences between PSHB 0.3/0.4 and this spec.

For each role: publishers, subscribers and hubs.

The spec leaves unsaid how redirections resulting from an (un)subscription POST to a hub are to be treated. Perhaps (un)subscribers SHOULD follow a (small number of) redirections at this point in the protocol? (And hubs SHOULD use codes 307 or 308 to redirect.)

Example use case: sharding based on callback URL. A hub receives a subscription request, determines which hub is responsible for the callback URL supplied in it, and redirects the subscriber to that hub.

the "hub" link relation type is used/introduced in this specification and not yet formally registered with IANA. it would be good if the spec had a section briefly explaining what "hub" is used for, as a link relation type, and a IANA considerations section registering the link header type with IANA.

Following the discussion in #27 it's apparent that the current language in section 6 isn't clear enough on whether fat pings are required or not and we should clarify that to avoid confusions going forward:

A content distribution request is an HTTP [RFC7231] POST request from hub to the subscriber's callback URL with the payload of the notification. This request must have a Content-Type corresponding to the type of the topic. The hub may reduce the payload to a diff between two consecutive versions if its format allows it.

It should be clarified what the payload sent with the notification is actually expected to contain and whether an empty payload is allowed. Some SHOULD, MAY, MUST language regarding the payload and the corresponding Content-Type would be good to ensure that subscribers and hubs knows what they can expect from each other and how to handle the different cases.

Pinging @julien51 and @aaronpk here as I believe you both have something to say in this regard.

Two implementations of each feature:

Subscribers

Discovery

• GET or HEAD request, looking for a Link header
• For XML documents, looking for the link tag
• For HTML documents, looking for the link tag
• .host-meta discovery

Subscription

• Request with callback, mode, topic
• Request with secret
• Request with lease_seconds
• Unsubscribing

Subscription Verification

• Acknowledge a pending subscription
• Reject an invalid topic URL

Distribution

• Return 2xx when the notification payload is delivered
• Verify a valid signature for authenticated distribution
• Reject an invalid signature for authenticated distribution
• Reject delivery with no signature if a secret was provided in the subscription request

Publisher

• Advertise a hub and self with Link headers
• Advertise a hub and self with a link tag in an XML document
• Advertise a hub and self with a link tag in an HTML document
• Advertise a hub and self with .host-meta discovery

Hub

Subscription

• Support subscriptions with just callback, mode, topic
• Support subscriptions with a secret, and computing signatures for delivery
• Respect requested lease_seconds
• Ignore requested lease_seconds
• Allow subscribers to re-request active subscriptions
• Support unsubscribe request

Distribution

• Send a notification with matching content type
• Send a notification with a signature when a secret was provided
• Ensure the hub sends the full content of the topic URL for all content types other than RSS/Atom

In the draft of 20 Oct 2016, section 6 contains:

The successful response from the subscriber's callback URL MUST be an HTTP [RFC7231] success (2xx) code. The hub MUST consider all other subscriber response codes as failures [...]

and recommends that after some unspecified amount of time, enough repeated failures should cause cessation of retry. (Issue #15 discusses what that might mean.)

However, some HTTP codes could be worth treating specially. In particular,

• 4xx should cause immediate deletion of the subscription
  • except, arguably, 408, 413, and possibly 411
• 5xx should probably be a strong signal that the subscription is probably broken; if not immediate unsubscription, then probably after a smaller number of retries than usual
  • except 503, which is explicitly a temporary condition, including an optional retry-after

For simplicity, perhaps it'd be OK to have

• 2xx: success!
• 3xx: failure, retry
• 4xx: failure, delete the subscription
• 5xx: failure, retry (taking into account retry-after if supplied and code is 503)

Or, is this getting too far into the weeds of setting policy? Perhaps just clearing up #15 is enough?

In the first paragraph of Discovery, the spec currently says that publishers MUST include an HTTP Link header. In the second paragraph, it says that subscribers MAY fall back to other methods of discovering the hub and topic, and suggests embedded link elements for XML and HTML documents. The inconsistency in the spec arises from the fact that if publishers are required to advertise the values in Link headers, then there is no need for consumers to check other places.

Either the spec should drop all mention of alternative methods and require publishers and consumers use HTTP headers, or it should explicitly allow publishers to advertise the values in the HTML or XML document.

We addressed this in Webmention by saying that senders are required to support both HTTP header and HTML based discovery. https://webmention.net/draft/#sender-discovers-receiver-webmention-endpoint

Personally, I would prefer not to limit discovery to only HTTP headers, since that precludes some websites from using it, so would like to do what Webmention did. Something along the lines of:

• Publishers SHOULD advertise the hub and topic in HTTP Link headers, and if the topic URL is HTML or XML, MAY instead advertise the values with a <link> tag.
• Subscribers MUST first check HTTP Link headers, and if the content type is HTML or XML and no values were found in the headers, then MUST check for <link> tags.

Add a section that describes the reference to PubSubHubbub to lower the confusion for existing implementations.

The WebSub spec does not specify whether it is okay to specify target attributes.

Would the following discovery link headers be okay?

Link: <http://example.org>; rel="self"; title="example",
	<http://example.org/hub>; rel="hub"; title="example hub"

Here is what the WebCryptoAPI has done, we should probably use text like this:

https://www.w3.org/TR/WebCryptoAPI/#sha

Section 4.1 says:

In the context of social web applications, it is considered good practice to include a From HTTP [RFC7231] header (as described in section 5.5.1 of Hypertext Transfer Protocol [RFC7231]) to indicate on behalf of which user the subscription is being performed.

From what I can tell, there is no actual benefit to including the header, especially since there is no guidelines on the verifiability/security of the value. On top of that, the From header must be an email address, and there are very few situations in which sharing a user's email address like this is acceptable.

My proposal is to drop this quoted sentence entirely. It will have no effect on the interoperability of existing implementations.

If a subscription is currently active for a subscriber that used a hub.secret when creating the initial subscription, is it okay if a new subscription request comes in without a hub.secret? It looks like just the topic and callback are used to identify a previous subscription:

... must override the previous subscription state for a specific topic URL and callback URL combination ...

I believe there is no risk in allowing a future request that doesn't have a secret, because:

Any failures to confirm the subscription action must leave the subscription state unchanged.

In particular, I'm thinking of a case where an attacker tries to make a subscription request for a subscriber that previously used a secret. When the subscriber gets a subscription request, it must only acknowledge the verification if it specifically requested it, otherwise it's possible for someone to turn a signed subscription into an unsigned subscription.

There are two issues I would like to see some clarification on:

1. Should a hub allow the secret of a subscription to be changed or removed or added? I think the answer is yes, but I feel like this should be made explicit in the spec since I had this question while implementing a hub.
2. We should add some text for subscribers to clarify the security requirements of their verification endpoint, to ensure an attacker can't accidentally cause them to confirm a malicious subscription.

Are there any known implementations of advertising the hub using the .host-meta method? If not, it's probably worth dropping that from the list of supported discovery methods.

Differentiate current authors from older author.

In the draft of 20 Oct 2016, no mention is made of acceptable values for hub.lease_seconds other than it be a "number".

1. Are non-integers accepted?
2. Are negative numbers accepted?
3. Are numbers in non-decimal bases accepted?

If non-integers are accepted, it might be worth pointing out that hub implementations should take care to properly handle very small values such as 0 or 0.000001. (And perhaps that they may round to the nearest whole number of seconds.)

I suggest forbidding negative numbers :-)

I also suggest forbidding non-decimal bases. (Some languages' standard libraries will automatically interpret '0xaa' as decimal 170.)

It might be simplest to specify that hub.lease_seconds must be a non-empty sequence of ASCII decimal digit characters (plus, perhaps, a signifier of an unbounded duration, depending on treatment of issue #17).

Finally, some very large integers, e.g. those larger than 2^31, 2^53 or 2^63, may also cause problems for hub implementations written in some programming languages. Would a note on reasonable ranges of lease times be in order? Or perhaps a note pointing out explicitly that no limit is in place, and that implementations should be prepared to deal with very large values?