 |
README: improve documentation of how it works, fix typos, etc - pubsubhubbubblu… |
 |
git clone git://git.codemadness.org/pubsubhubbubblub |
 |
Log |
|
Files |
|
Refs |
|
README |
|
LICENSE |
|
--- |
|
commit 4c38584b997b02111a7c63becb249ba1e491eb39 |
|
parent e5180265f1b2d6713de0de2efb01f22b18d388c8 |
|
Author: Hiltjo Posthuma <[email protected]> |
|
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(-) |
|
--- |
|
diff --git a/README b/README |
|
@@ -8,16 +8,17 @@ It has some helper scripts to use it with RSS/Atom feeds and … |
|
What is it |
|
---------- |
|
|
|
-pubsubhubbub is a publisher/subscriber technology used to push updates in a we… |
|
-This allows to push content updates, instead of polling for news in an interva… |
|
+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 interva… |
|
|
|
|
|
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 h… |
|
|
|
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://pubsub… |
|
-/pubsub-data/config/feedname/topic - hub.topic, the feed URL. |
|
-/pubsub-data/config/feedname/secret - hub.secret for calculating the message… |
|
- see Section 8 of Pubsubhubbub core 0.4… |
|
-/pubsub-data/config/feedname/token - File containing a line with a secret t… |
|
- sure an entrypoint is not easy guessab… |
|
- hubs etc (optional). |
|
-/pubsub-data/feeds/feedname/ - Directory containing processed message… |
|
-/pubsub-data/tmp/feedname/ - Temporary directory to process message… |
|
- Moves to the feeds/feedname directory … |
|
-/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… |
|
+- 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 l… |
|
+ |
|
+ |
|
+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.appspo… |
|
+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 ma… |
|
+ sure an entrypoint is not easy guessable by differe… |
|
+ 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 |
|
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}" "subscrib… |
|
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}" "unsubscr… |
|
rm -f "config/${feedname}/callback" |
|
rm -f "config/${feedname}/hub" |
