GopherProxy

	README - pubsubhubbubblub - pubsubhubbub client implementation
	git clone git://git.codemadness.org/pubsubhubbubblub
	Log
	Files
	Refs
	README
	LICENSE
	---
	README (5032B)
	---
	1 pubsubhubbubblub
	2 ----------------
	3
	4 Generic pubsubhubbub client implementation.
	5 It has some helper scripts to use it with RSS/Atom feeds and with sfeed.
	6
	7
	8 What is it
	9 ----------
	10
	11 pubsubhubbub is a publisher/subscriber technology used to push updates i…
	12 webhook-like way.
	13 This allows to push content updates, instead of polling for data in an i…
	14
	15
	16 Features
	17 --------
	18
	19 - Relatively simple.
	20 - Uses pledge(2) and unveil(2) on OpenBSD.
	21 - Signature verification support (hub.secret), Pubsubhub 0.4 core SHA1 o…
	22
	23
	24 Dependencies
	25 ------------
	26
	27 - C compiler (C99).
	28 - libc (recommended: C99 and POSIX >= 200809).
	29 - httpd and CGI handler.
	30
	31
	32 Optional dependencies
	33 ---------------------
	34
	35 - POSIX make(1) for the Makefile.
	36 - POSIX sh(1), used by pubsub_setup.
	37 - curl(1) binary: https://curl.haxx.se/ ,
	38 used by pubsub_setup for subscribing and unsubscribing to a hub.
	39
	40
	41 Files
	42 -----
	43
	44 pubsub_cgi.c - Small stupid PubSubHubBub implementation as a CGI progra…
	45 pubsub_gethub - Helper program extract a hub and feed URL from a RSS or …
	46 pubsub_setup - Helper script that sets up the directory structure for
	47 processing the feed for the CGI program. It has an -s op…
	48 subscribe and an -u option to unsubscribe at a hub also.
	49
	50
	51 How to install
	52 --------------
	53
	54 To build it run:
	55
	56 make
	57
	58 Install:
	59
	60 cp pubsub_gethub pubsub_setup /usr/local/bin
	61 cp pubsub_cgi /var/www/cgi-bin/pubsub
	62
	63
	64 A configuration example for the CGI program using OpenBSD httpd and slow…
	65
	66 location "/pubsub/**" {
	67 request strip 1
	68 root "/cgi-bin/pubsub"
	69 fastcgi socket "/run/slowcgi.sock"
	70 }
	71
	72 Compile pubsub_cgi.c statically and copy it to /var/www/cgi-bin/pubsub
	73
	74 - Create a directory with write-access for the pubsub CGI program, for e…
	75 /var/www/pubsub-data/feedname. The pubsub_setup script can be used to…
	76 the directories for a feed.
	77 - Make sure to set the proper permissions for the CGI program (slowcgi) …
	78 HTTPd, for example www:daemon.
	79 - The relative path name of the path to the CGI script (served via the H…
	80 can be changed in the pubsub_setup script.
	81
	82
	83 How does it work
	84 ----------------
	85
	86 - The CGI program runs at an entrypoint served by a httpd, for example:
	87 https://codemadness.org/pubsub/slashdot/secrettoken
	88 - This URL is registered at a hub as the callback URL.
	89 - When subscribing the hub sends a confirmed request to this callback UR…
	90 - The hub sends then messages using HTTP POST to this callback URL.
	91 - The CGI program processes these messages and writes them to a feed dir…
	92 - It writes the request entry of a successfuly processed message to a gl…
	93
	94
	95 Directory structure, relative to for example /var/www/pubsub-data:
	96
	97 config/feedname/ - Directory with metadata about the feed.
	98 config/feedname/callback - The hub.callback URL used to subscribe.
	99 config/feedname/hub - The hub URL, for example http://pubsubhubbub.…
	100 config/feedname/topic - hub.topic, the feed URL.
	101 config/feedname/secret - hub.secret for calculating the message digest,
	102 see Section 8 of Pubsubhubbub core 0.4 (optio…
	103 config/feedname/token - File containing a line with a secret token. T…
	104 sure an entrypoint is not easy guessable by d…
	105 hubs etc (optional).
	106 feeds/feedname/ - Directory containing processed messages.
	107 tmp/feedname/ - Temporary directory to process messages.
	108 Moves to the feeds/feedname directory on succ…
	109 log - Log file, TAB-separated.
	110
	111
	112 Example
	113 -------
	114
	115 Get the hub and feed URL:
	116
	117 curl -s http://rss.slashdot.org/Slashdot/slashdot \| pubsub_gethub
	118
	119 http://rss.slashdot.org/Slashdot/slashdot self
	120 http://pubsubhubbub.appspot.com/ hub
	121
	122
	123 Setup the feed structure for the CGI program and also subscribe to the h…
	124
	125 cd /var/www/pubsub-data
	126 pubsub_setup \
	127 -b 'https://codemadness.org/pubsub/' \
	128 -f 'slashdot' \
	129 -h 'http://pubsubhubbub.appspot.com/' \
	130 -t 'http://rss.slashdot.org/Slashdot/slashdot'
	131 pubsub_setup -s -f 'slashdot'
	132
	133
	134 Unsubscribe from a hub:
	135
	136 cd /var/www/pubsub-data
	137 pubsub_setup -u -f 'slashdot'
	138
	139
	140 Monitor script example
	141 ----------------------
	142
	143 This monitors the log file using tail(1) -f for new messages. It uses s…
	144 and sfeed_plain to process the new message (assuming it's RSS/Atom) and …
	145 it to a plain-text list.
	146
	147 #!/bin/sh
	148 cd /var/www/pubsub-data
	149 tail -f log \| \
	150 LC_ALL=C awk '{ print $2 "\t" $3; fflush(); }' \| \
	151 while IFS=" " read -r feed file; do sfeed < "feed…
	152 sfeed_plain
	153
	154
	155 This can then be piped to the suckless ii(1) program for IRC notificatio…
	156 Of course the sfeed_plain program can be replaced by sfeed_mbox and a MT…
	157 mail notifications too.
	158
	159
	160 References
	161 ----------
	162
	163 Pubsubhubbub core 0.4: https://pubsubhubbub.github.io/PubSubHubbub/pubsu…