FeedSub.php

Summary
FeedSub.php
FeedSubClass representation of an individual feed subscription
FeedSubTable definition for an ostatus feed subscription
schemaDefReturns an array that represents the database schema of the FeedSub
getUriReturns the feed uri (http/https)
getLeaseRemainingReturns how long before the feedsub expires and must be renewed
isPuSHReturns whether or not this is a PuSH feed
localProfileFetch the profile for a local user we are subscribed to
ensureFeedRun discovery on a URI to see if it is a feed we can subscribe to.
subscribeSend a subscription request to the hub for this feed.
unsubscribeSend a PuSH unsubscription request to the hub for this feed.
garbageCollectCheck if there are any active local uses of this feed, and if not then make sure it’s inactive, unsubscribing if necessary.
renewalCheckSearch for FeedSubs that need renewed
renewRenews a feedsub, which is basically just running the subscription again.
doSubscribeSetting to subscribe means it is waiting to become active.
confirmSubscribeSave PuSH subscription confirmation.
confirmUnsubscribeSave PuSH unsubscription confirmation.
receiveAccept updates from a PuSH feed.
validatePushSigValidate the given Atom chunk and HMAC signature against our shared secret that was set up at subscription time.
deleteDeletes a FeedSub from the database

FeedSub

Class representation of an individual feed subscription

postActiv

the micro-blogging software

Copyright

Copyright © 2016-2017, Maiyannah Bishop

Derived from code copyright various sources

  • GNU Social © 2013-2016, Free Software Foundation, Inc
  • StatusNet © 2008-2012, StatusNet, Inc

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program.  If not, see http://www.gnu.org/licenses/.

https://www.gnu.org/licenses/agpl.html

About

Class representation of an individual feed subscription

FeedSub handles low-level PubHubSubbub (PuSH) subscriptions.  Higher-level behavior building OStatus stuff on top is handled under Ostatus_profile.

PuSH subscription flow

$profile->subscribe() sends a sub request to the hub...

main/push/callback hub sends confirmation back to us via GET We verify the request, then echo back the challenge.  On our end, we save the time we subscribed and the lease expiration

main/push/callback hub sends us updates via POST

PHP version

Tested with PHP 7

File Authors

Web

FeedSub

Table definition for an ostatus feed subscription

Summary
schemaDefReturns an array that represents the database schema of the FeedSub
getUriReturns the feed uri (http/https)
getLeaseRemainingReturns how long before the feedsub expires and must be renewed
isPuSHReturns whether or not this is a PuSH feed
localProfileFetch the profile for a local user we are subscribed to
ensureFeedRun discovery on a URI to see if it is a feed we can subscribe to.
subscribeSend a subscription request to the hub for this feed.
unsubscribeSend a PuSH unsubscription request to the hub for this feed.
garbageCollectCheck if there are any active local uses of this feed, and if not then make sure it’s inactive, unsubscribing if necessary.
renewalCheckSearch for FeedSubs that need renewed
renewRenews a feedsub, which is basically just running the subscription again.
doSubscribeSetting to subscribe means it is waiting to become active.
confirmSubscribeSave PuSH subscription confirmation.
confirmUnsubscribeSave PuSH unsubscription confirmation.
receiveAccept updates from a PuSH feed.
validatePushSigValidate the given Atom chunk and HMAC signature against our shared secret that was set up at subscription time.
deleteDeletes a FeedSub from the database

schemaDef

public static function schemaDef()

Returns an array that represents the database schema of the FeedSub

getUri

public function getUri()

Returns the feed uri (http/https)

Returns

string URI

Error States

  • throws a NoUriException if there is no saved URI of the FeedSub

getLeaseRemaining

function getLeaseRemaining()

Returns how long before the feedsub expires and must be renewed

Returns

  • integer representing remaining time before expiry
  • null if the sub is expired

isPuSH

public function isPuSH()

Returns whether or not this is a PuSH feed

Do we have a hub?  Then we are a PuSH feed.  https://en.wikipedia.org/wiki/PubSubHubbub

If huburi is empty, then doublecheck that we are not using a fallback hub.  If there is a fallback hub, it is only if the sub_state is “nohub” that we assume it’s not a PuSH feed.

Returns

  • boolean True or False

localProfile

public function localProfile()

Fetch the profile for a local user we are subscribed to

Returns

  • Profile Local_profile

ensureFeed

public static function ensureFeed($feeduri)

Run discovery on a URI to see if it is a feed we can subscribe to.

Parameters

  • string $feeduri

Returns

  • created or existing FeedSub

Error States

  • throws FeedSubException if feed is invalid or lacks PuSH setup

subscribe

public function subscribe()

Send a subscription request to the hub for this feed.  The hub will later send us a confirmation POST to /main/push/callback.

Error States

  • throws ServerException if feed state is not valid

unsubscribe

public function unsubscribe()

Send a PuSH unsubscription request to the hub for this feed.  The hub will later send us a confirmation POST to /main/push/callback.

Warning: this will cancel the subscription even if someone else in the system is using it.  Most callers will want garbageCollect() instead, which confirms there’s no uses left.

Error States

  • throws ServerException if feed state is not valid

garbageCollect

public function garbageCollect()

Check if there are any active local uses of this feed, and if not then make sure it’s inactive, unsubscribing if necessary.

Returns

  • boolean true if the subscription is now inactive, false if still active.

Error States

  • throws NoProfileException in FeedSubSubscriberCount for missing Profile entries
  • throws Exception if something goes wrong in unsubscribe() method

renewalCheck

static public function renewalCheck()

Search for FeedSubs that need renewed

renew

public function renew()

Renews a feedsub, which is basically just running the subscription again.

doSubscribe

protected function doSubscribe($mode)

Setting to subscribe means it is waiting to become active.  This cannot be done in a transaction because there is a chance that the remote script we’re calling (as in the case of PuSHpress) performs the lookup while we’re POSTing data, which means the transaction never completes (PushcallbackAction gets an ‘inactive’ state).

Returns

  • boolean true when everything is ok (throws Exception on fail)

Error States

  • throws Exception on failure, can be HTTPClient’s or our own.

confirmSubscribe

public function confirmSubscribe($lease_seconds)

Save PuSH subscription confirmation.  Sets approximate lease start and end times and finalizes state.

Parameters

  • int $lease_seconds - provided hub.lease_seconds parameter, if given

confirmUnsubscribe

public function confirmUnsubscribe()

Save PuSH unsubscription confirmation.  Wipes active PuSH sub info and resets state.

Returns

  • FeedSub Updated

receive

public function receive($post,
$hmac)

Accept updates from a PuSH feed.  If validated, this object and the feed (as a DOMDocument) will be passed to the StartFeedSubHandleFeed and EndFeedSubHandleFeed events for processing.

Not guaranteed to be running in an immediate POST context; may be run from a queue handler.

Parameters

  • string $post source of Atom or RSS feed
  • string $hmac X-Hub-Signature header, if present

Side effects

  • the feedsub record’s lastupdate field will be updated to the current time (not published time) if we got a legit update.

Returns

  • void

validatePushSig

protected function validatePushSig($post,
$hmac)

Validate the given Atom chunk and HMAC signature against our shared secret that was set up at subscription time.

If we don’t have a shared secret, there should be no signature.  If we do, our calculated HMAC should match theirs.

Parameters

  • string $post raw XML source as POSTed to us
  • string $hmac X-Hub-Signature HTTP header value, or empty

Returns

  • boolean true for a match

delete

public function delete($useWhere = false)

Deletes a FeedSub from the database

Returns

  • boolean Success
public static function schemaDef()
Returns an array that represents the database schema of the FeedSub
public function getUri()
Returns the feed uri (http/https)
function getLeaseRemaining()
Returns how long before the feedsub expires and must be renewed
public function isPuSH()
Returns whether or not this is a PuSH feed
public function localProfile()
Fetch the profile for a local user we are subscribed to
public static function ensureFeed($feeduri)
Run discovery on a URI to see if it is a feed we can subscribe to.
public function subscribe()
Send a subscription request to the hub for this feed.
public function unsubscribe()
Send a PuSH unsubscription request to the hub for this feed.
public function garbageCollect()
Check if there are any active local uses of this feed, and if not then make sure it’s inactive, unsubscribing if necessary.
static public function renewalCheck()
Search for FeedSubs that need renewed
public function renew()
Renews a feedsub, which is basically just running the subscription again.
protected function doSubscribe($mode)
Setting to subscribe means it is waiting to become active.
public function confirmSubscribe($lease_seconds)
Save PuSH subscription confirmation.
public function confirmUnsubscribe()
Save PuSH unsubscription confirmation.
public function receive($post,
$hmac)
Accept updates from a PuSH feed.
protected function validatePushSig($post,
$hmac)
Validate the given Atom chunk and HMAC signature against our shared secret that was set up at subscription time.
public function delete($useWhere = false)
Deletes a FeedSub from the database