HubSub.php

Summary
HubSub.php
HubSubClass representation of a PuSH hub subscription
HubSubPuSH feed subscription record
schemaDefReturns an array describing the table schema in the database
hashkeyGiven a topic and callback, compute the sha1 hash for a HubSub
getByHashkeyGiven the topic and callback of a HubSub, find it in the database
setLeaseValidates a requested lease length, sets length plus subscription start & end dates.
getLeaseTimeReturns the remaining time on a hubsub lease
getLeaseRemainingEssentially a call to getLeaseTime but with some extra checking
scheduleVerifySchedule a future verification ping to the subscriber.
getTopicReturns the HubSub’s topic
verifySend a verification ping to subscriber, and if confirmed apply the changes.
onInsertSets the hashkey automagically on insert
onUpdateKeysUpdate the hashkey automagically if needed
setHashkeyHelper function to actually set the hashkey
distributeSchedule delivery of a ‘fat ping’ to the subscriber’s callback endpoint.
bulkDistributeQueue up a large batch of pushes to multiple subscribers for this same topic update.
pushSend a ‘fat ping’ to the subscriber’s callback endpoint containing the given Atom feed chunk.

HubSub

Class representation of a PuSH hub 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 a PuSH hub subscription

HubSub 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

HubSub

PuSH feed subscription record

Variables

  • hashkey - sha1(topic . ‘|’ . $callback); (topic, callback) key is too long for myisam in utf8
  • topic - varchar(191) not 255 because utf8mb4 takes more space
  • callback - varchar(191) not 255 because utf8mb4 takes more space
  • secret - text
  • sub_start - datetime
  • sub_end - datetime
  • created - datetime
  • modified - timestamp
Summary
schemaDefReturns an array describing the table schema in the database
hashkeyGiven a topic and callback, compute the sha1 hash for a HubSub
getByHashkeyGiven the topic and callback of a HubSub, find it in the database
setLeaseValidates a requested lease length, sets length plus subscription start & end dates.
getLeaseTimeReturns the remaining time on a hubsub lease
getLeaseRemainingEssentially a call to getLeaseTime but with some extra checking
scheduleVerifySchedule a future verification ping to the subscriber.
getTopicReturns the HubSub’s topic
verifySend a verification ping to subscriber, and if confirmed apply the changes.
onInsertSets the hashkey automagically on insert
onUpdateKeysUpdate the hashkey automagically if needed
setHashkeyHelper function to actually set the hashkey
distributeSchedule delivery of a ‘fat ping’ to the subscriber’s callback endpoint.
bulkDistributeQueue up a large batch of pushes to multiple subscribers for this same topic update.
pushSend a ‘fat ping’ to the subscriber’s callback endpoint containing the given Atom feed chunk.

schemaDef

public static function schemaDef()

Returns an array describing the table schema in the database

hashkey

static function hashkey($topic,
$callback)

Given a topic and callback, compute the sha1 hash for a HubSub

Parameters

  • topic - topic of the hubsub
  • callback - callback URL of the hubsub

Returns

  • sha1 Hash

getByHashkey

public static function getByHashkey($topic,
$callback)

Given the topic and callback of a HubSub, find it in the database

Parameters

  • topic - topic of the hubsub
  • callback - callback URL of the hubsub

Returns

  • found hubsub

setLease

function setLease($length)

Validates a requested lease length, sets length plus subscription start & end dates.

Does not save to database -- use before insert() or update().

Parameters

  • int $length - length of lease in seconds

getLeaseTime

function getLeaseTime()

Returns the remaining time on a hubsub lease

Returns

  • int $length

getLeaseRemaining

function getLeaseRemaining()

Essentially a call to getLeaseTime but with some extra checking

Returns

  • null if the lease is expired
  • int $length otherwise

scheduleVerify

function scheduleVerify($mode,  
$token = null,
$retries = null)

Schedule a future verification ping to the subscriber.  If queues are disabled, will be immediate.

Parameters

  • string $mode - ‘subscribe’ or ‘unsubscribe’
  • string $token - hub.verify_token value, if provided by client

getTopic

public function getTopic()

Returns the HubSub’s topic

Returns

  • $topic

verify

function verify($mode,  
$token = null)

Send a verification ping to subscriber, and if confirmed apply the changes.  This may create, update, or delete the database record.

Parameters

  • string $mode - ‘subscribe’ or ‘unsubscribe’
  • string $token - hub.verify_token value, if provided by client

Error States

  • throws ClientException on failure

onInsert

protected function onInsert()

Sets the hashkey automagically on insert

onUpdateKeys

protected function onUpdateKeys(Managed_DataObject $orig)

Update the hashkey automagically if needed

setHashkey

protected function setHashkey()

Helper function to actually set the hashkey

distribute

function distribute($atom,  
$retries = null)

Schedule delivery of a ‘fat ping’ to the subscriber’s callback endpoint.  If queues are disabled, this will run immediately.

Parameters

  • string $atom - well-formed Atom feed
  • int $retries - optional count of retries if POST fails; defaults to hub_retries from config or 0 if unset

bulkDistribute

function bulkDistribute( $atom,
array $pushCallbacks)

Queue up a large batch of pushes to multiple subscribers for this same topic update.

If queues are disabled, this will run immediately.

Parameters

  • string $atom well-formed Atom feed
  • array $pushCallbacks list of callback URLs

Returns

  • boolean True for success, False for failure

push

function push($atom)

Send a ‘fat ping’ to the subscriber’s callback endpoint containing the given Atom feed chunk.

Determination of which items to send should be done at a higher level; don’t just shove in a complete feed!

Parameters

  • string $atom - well-formed Atom feed

Error States

  • throws Exception (HTTP or general)
public static function schemaDef()
Returns an array describing the table schema in the database
static function hashkey($topic,
$callback)
Given a topic and callback, compute the sha1 hash for a HubSub
public static function getByHashkey($topic,
$callback)
Given the topic and callback of a HubSub, find it in the database
function setLease($length)
Validates a requested lease length, sets length plus subscription start & end dates.
function getLeaseTime()
Returns the remaining time on a hubsub lease
function getLeaseRemaining()
Essentially a call to getLeaseTime but with some extra checking
function scheduleVerify($mode,  
$token = null,
$retries = null)
Schedule a future verification ping to the subscriber.
public function getTopic()
Returns the HubSub’s topic
function verify($mode,  
$token = null)
Send a verification ping to subscriber, and if confirmed apply the changes.
protected function onInsert()
Sets the hashkey automagically on insert
protected function onUpdateKeys(Managed_DataObject $orig)
Update the hashkey automagically if needed
protected function setHashkey()
Helper function to actually set the hashkey
function distribute($atom,  
$retries = null)
Schedule delivery of a ‘fat ping’ to the subscriber’s callback endpoint.
function bulkDistribute( $atom,
array $pushCallbacks)
Queue up a large batch of pushes to multiple subscribers for this same topic update.
function push($atom)
Send a ‘fat ping’ to the subscriber’s callback endpoint containing the given Atom feed chunk.