gnu-social/plugins/TwitterBridge
Brion Vibber 26fdf0c9d2 XMPP queued output & initial retooling of DB queue manager to support non-Notice objects.
Queue handlers for XMPP individual & firehose output now send their XML stanzas
to another output queue instead of connecting directly to the chat server. This
lets us have as many general processing threads as we need, while all actual
XMPP input and output go through a single daemon with a single connection open.

This avoids problems with multiple connected resources:
* multiple windows shown in some chat clients (psi, gajim, kopete)
* extra load on server
* incoming message delivery forwarding issues

Database changes:
* queue_item drops 'notice_id' in favor of a 'frame' blob.
  This is based on Craig Andrews' work branch to generalize queues to take any
  object, but conservatively leaving out the serialization for now.
  Table updater (preserves any existing queued items) in db/rc3to09.sql

Code changes to watch out for:
* Queue handlers should now define a handle() method instead of handle_notice()
* QueueDaemon and XmppDaemon now share common i/o (IoMaster) and respawning
  thread management (RespawningDaemon) infrastructure.
* The polling XmppConfirmManager has been dropped, as the message is queued
  directly when saving IM settings.
* Enable $config['queue']['debug_memory'] to output current memory usage at
  each run through the event loop to watch for memory leaks

To do:
* Adapt XMPP i/o to component connection mode for multi-site support.
* XMPP input can also be broken out to a queue, which would allow the actual
  notice save etc to be handled by general queue threads.
* Make sure there are no problems with simply pushing serialized Notice objects
  to queues.
* Find a way to improve interactive performance of the database-backed queue
  handler; polling is pretty painful to XMPP.
* Possibly redo the way QueueHandlers are injected into a QueueManager. The
  grouping used to split out the XMPP output queue is a bit awkward.
2010-01-21 16:42:50 -08:00
..
daemons Merge branch '0.9.x' into inblob 2010-01-12 23:53:52 -08:00
locale New _m() gettext wrapper with smart detection of plugin domains. Plugin base class registers your gettext files if present at initialization. 2009-12-08 12:17:11 -08:00
README use addPlugin() in the README setup example 2009-10-29 15:08:24 -04:00
twitter.php When Twitter bridge encounters a 403 (rate limit) err, drop the notice 2010-01-13 19:17:40 +00:00
twitterauthorization.php New _m() gettext wrapper with smart detection of plugin domains. Plugin base class registers your gettext files if present at initialization. 2009-12-08 12:17:11 -08:00
twitterbasicauthclient.php Fix Twitter bridge so it responds reasonably to authorization errors. 2009-12-14 07:33:29 +00:00
TwitterBridgePlugin.php Major refactoring of queue handlers to support running multiple sites in one daemon. 2010-01-12 20:45:09 -08:00
twitteroauthclient.php Merge branch '0.9.x' into pluginize-twitter-bridge 2009-09-08 16:02:57 -07:00
twitterqueuehandler.php XMPP queued output & initial retooling of DB queue manager to support non-Notice objects. 2010-01-21 16:42:50 -08:00
twittersettings.php New _m() gettext wrapper with smart detection of plugin domains. Plugin base class registers your gettext files if present at initialization. 2009-12-08 12:17:11 -08:00

This Twitter "bridge" plugin allows you to integrate your StatusNet
instance with Twitter.  Installing it will allow your users to:

    - automatically post notices to thier Twitter accounts
    - automatically subscribe to other Twitter users who are also using
      your StatusNet install, if possible (requires running a daemon)
    - import their Twitter friends' tweets (requires running a daemon)

Installation
------------

To enable the plugin, add the following to your config.php:

    addPlugin("TwitterBridge");

OAuth is used to to access protected resources on Twitter (as opposed to
HTTP Basic Auth)*.  To use Twitter bridging you will need to register
your instance of StatusNet as an application on Twitter
(http://twitter.com/apps), and update the following variables in your
config.php with the consumer key and secret Twitter generates for you:

    $config['twitter']['consumer_key']    = 'YOURKEY';
    $config['twitter']['consumer_secret'] = 'YOURSECRET';

When registering your application with Twitter set the type to "Browser"
and your Callback URL to:

    http://example.org/mublog/twitter/authorization

The default access type should be, "Read & Write".

* Note: The plugin will still push notices to Twitter for users who
  have previously setup the Twitter bridge using their Twitter name and
  password under an older versions of StatusNet, but all new Twitter
  bridge connections will use OAuth.

Deamons
-------

For friend syncing and importing notices running two additional daemon
scripts is necessary (synctwitterfriends.php and
twitterstatusfetcher.php).

In the daemons subidrectory of the plugin are three scripts:

* Twitter Friends Syncing (daemons/synctwitterfriends.php)

Users may set a flag in their settings ("Subscribe to my Twitter friends
here" under the Twitter tab) to have StatusNet attempt to locate and
subscribe to "friends" (people they "follow") on Twitter who also have
accounts on your StatusNet system, and who have previously set up a link
for automatically posting notices to Twitter.

The plugin will try to start this daemon when you run
scripts/startdaemons.sh.

* Importing statuses from Twitter (daemons/twitterstatusfetcher.php)

To allow your users to import their friends' Twitter statuses, you will
need to enable the bidirectional Twitter bridge in your config.php:

    $config['twitterimport']['enabled'] = true;

The plugin will then start the TwitterStatusFetcher daemon along with the
other daemons when you run scripts/startdaemons.sh.

Additionally, you will want to set the integration source variable,
which will keep notices posted to Twitter via StatusNet from looping
back.  The integration source should be set to the name of your
application, exactly as you specified it on the settings page for your
StatusNet application on Twitter, e.g.:

    $config['integration']['source'] = 'YourApp';

* TwitterQueueHandler (daemons/twitterqueuehandler.php)

This script sends queued notices to Twitter for user who have opted to
set up Twitter bridging.

It's not strictly necessary to run this queue handler, and sites that
haven't enabled queuing are still able to push notices to Twitter, but
for larger sites and sites that wish to improve performance, this
script allows notices to be sent "offline" via a separate process.

The plugin will start this script when you run scripts/startdaemons.sh.