README: improve documentation of how it works, fix typos, etc - pubsubhubbubblub - pubsubhubbub client implementation
HTML git clone git://git.codemadness.org/pubsubhubbubblub
DIR Log
DIR Files
DIR Refs
DIR README
DIR LICENSE
---
DIR commit 4c38584b997b02111a7c63becb249ba1e491eb39
DIR parent e5180265f1b2d6713de0de2efb01f22b18d388c8
HTML Author: Hiltjo Posthuma <hiltjo@codemadness.org>
Date: Sat, 28 May 2022 12:58:41 +0200
README: improve documentation of how it works, fix typos, etc
Diffstat:
M README | 63 ++++++++++++++++++-------------
M pubsub_setup | 4 ++--
2 files changed, 38 insertions(+), 29 deletions(-)
---
DIR diff --git a/README b/README
@@ -8,16 +8,17 @@ It has some helper scripts to use it with RSS/Atom feeds and with sfeed.
What is it
----------
-pubsubhubbub is a publisher/subscriber technology used to push updates in a webhook-like way.
-This allows to push content updates, instead of polling for news in an interval.
+pubsubhubbub is a publisher/subscriber technology used to push updates in a
+webhook-like way.
+This allows to push content updates, instead of polling for data in an interval.
Features
--------
-- Not many dependencies.
-- Uses pledge and unveil on OpenBSD.
-- Signatures (hub.secret) support, Pubsubhub 0.4 core SHA1 only.
+- Relatively simple.
+- Uses pledge(2) and unveil(2) on OpenBSD.
+- Signature verification support (hub.secret), Pubsubhub 0.4 core SHA1 only.
Dependencies
@@ -25,6 +26,7 @@ Dependencies
- C compiler (C99).
- libc (recommended: C99 and POSIX >= 200809).
+- httpd and CGI handler.
Optional dependencies
@@ -69,35 +71,42 @@ A configuration example for the CGI program using OpenBSD httpd and slowcgi, htt
Compile pubsub_cgi.c statically and copy it to /var/www/cgi-bin/pubsub
-- Create a directory with write-access for the pubsub CGI program
+- Create a directory with write-access for the pubsub CGI program, for example
/var/www/pubsub-data/feedname. The pubsub_setup script can be used to create
- the directories.
+ the directories for a feed.
- Make sure to set the proper permissions for the CGI program (slowcgi) and
- HTTPd.
-- The base name of the CGI script can be changed in the pubsub_setup script.
+ HTTPd, for example www:daemon.
+- The relative path name of the path to the CGI script (served via the HTTPd)
+ can be changed in the pubsub_setup script.
How does it work
----------------
-The CGI program https://codemadness.org/pubsub/slashdot/secrettoken
-
-
-Directory structure:
-
-/pubsub-data/config/feedname/ - Directory with metadata about the feed.
-/pubsub-data/config/feedname/callback - The hub.callback URL used to subscribe.
-/pubsub-data/config/feedname/hub - The hub URL, for example http://pubsubhubbub.appspot.com/ .
-/pubsub-data/config/feedname/topic - hub.topic, the feed URL.
-/pubsub-data/config/feedname/secret - hub.secret for calculating the message digest,
- see Section 8 of Pubsubhubbub core 0.4 (optional).
-/pubsub-data/config/feedname/token - File containing a line with a secret token. This makes
- sure an entrypoint is not easy guessable by different
- hubs etc (optional).
-/pubsub-data/feeds/feedname/ - Directory containing processed messages.
-/pubsub-data/tmp/feedname/ - Temporary directory to process messages.
- Moves to the feeds/feedname directory on success.
-/pubsub-data/log - Log file, TAB-separated.
+- The CGI program runs at an entrypoint served by a httpd, for example:
+ https://codemadness.org/pubsub/slashdot/secrettoken
+- This URL is registered at a hub as the callback URL.
+- When subscribing the hub sends a confirmed request to this callback URL. The CGI program confirms this.
+- The hub sends then messages using HTTP POST to this callback URL.
+- The CGI program processes these messages and writes them to a feed directory.
+- It writes the request entry of a successfuly processed message to a global log file.
+
+
+Directory structure, relative to for example /var/www/pubsub-data:
+
+config/feedname/ - Directory with metadata about the feed.
+config/feedname/callback - The hub.callback URL used to subscribe.
+config/feedname/hub - The hub URL, for example http://pubsubhubbub.appspot.com/ .
+config/feedname/topic - hub.topic, the feed URL.
+config/feedname/secret - hub.secret for calculating the message digest,
+ see Section 8 of Pubsubhubbub core 0.4 (optional).
+config/feedname/token - File containing a line with a secret token. This makes
+ sure an entrypoint is not easy guessable by different
+ hubs etc (optional).
+feeds/feedname/ - Directory containing processed messages.
+tmp/feedname/ - Temporary directory to process messages.
+ Moves to the feeds/feedname directory on success.
+log - Log file, TAB-separated.
Example
DIR diff --git a/pubsub_setup b/pubsub_setup
@@ -121,7 +121,7 @@ if test "${dosubscribe}" = "1"; then
exit 1
fi
- # register at hub. save state when succesfully registered.
+ # register at hub. save state when successfully registered.
if subscribe "${feedname}" "${hub}" "${topic}" "${callback}" "subscribe" "${secret}"; then
printf '%s\n' "${callback}" > "config/${feedname}/callback"
printf '%s\n' "${hub}" > "config/${feedname}/hub"
@@ -132,7 +132,7 @@ if test "${dosubscribe}" = "1"; then
fi
if test "${dounsubscribe}" = "1"; then
- # unregister at hub. remove state when succesfully registered.
+ # unregister at hub. remove state when successfully registered.
if subscribe "${feedname}" "${hub}" "${topic}" "${callback}" "unsubscribe" "${secret}"; then
rm -f "config/${feedname}/callback"
rm -f "config/${feedname}/hub"