lib/implugin.php

   1 <?php
   2 /**
   3  * StatusNet, the distributed open-source microblogging tool
   4  *
   5  * Superclass for plugins that do instant messaging
   6  *
   7  * PHP version 5
   8  *
   9  * LICENCE: This program is free software: you can redistribute it and/or modify
  10  * it under the terms of the GNU Affero General Public License as published by
  11  * the Free Software Foundation, either version 3 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU Affero General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Affero General Public License
  20  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  21  *
  22  * @category  Plugin
  23  * @package   StatusNet
  24  * @author    Craig Andrews <candrews@integralblue.com>
  25  * @license   http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
  26  * @link      http://status.net/
  27  */
  28
  29 if (!defined('STATUSNET') && !defined('LACONICA')) {
  30     exit(1);
  31 }
  32
  33 /**
  34  * Superclass for plugins that do authentication
  35  *
  36  * Implementations will likely want to override onStartIoManagerClasses() so that their
  37  *   IO manager is used
  38  *
  39  * @category Plugin
  40  * @package  StatusNet
  41  * @author   Craig Andrews <candrews@integralblue.com>
  42  * @license  http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
  43  * @link     http://status.net/
  44  */
  45 abstract class ImPlugin extends Plugin
  46 {
  47     //name of this IM transport
  48     public $transport = null;
  49     //list of screennames that should get all public notices
  50     public $public = array();
  51
  52     /**
  53      * normalize a screenname for comparison
  54      *
  55      * @param string $screenname screenname to normalize
  56      *
  57      * @return string an equivalent screenname in normalized form
  58      */
  59     abstract function normalize($screenname);
  60
  61     /**
  62      * validate (ensure the validity of) a screenname
  63      *
  64      * @param string $screenname screenname to validate
  65      *
  66      * @return boolean
  67      */
  68     abstract function validate($screenname);
  69
  70     /**
  71      * get the internationalized/translated display name of this IM service
  72      *
  73      * @return string
  74      */
  75     abstract function getDisplayName();
  76
  77     /**
  78      * send a single notice to a given screenname
  79      * The implementation should put raw data, ready to send, into the outgoing
  80      *   queue using enqueueOutgoingRaw()
  81      *
  82      * @param string $screenname screenname to send to
  83      * @param Notice $notice notice to send
  84      *
  85      * @return boolean success value
  86      */
  87     function sendNotice($screenname, Notice $notice)
  88     {
  89         return $this->sendMessage($screenname, $this->formatNotice($notice));
  90     }
  91
  92     /**
  93      * send a message (text) to a given screenname
  94      * The implementation should put raw data, ready to send, into the outgoing
  95      *   queue using enqueueOutgoingRaw()
  96      *
  97      * @param string $screenname screenname to send to
  98      * @param Notice $body text to send
  99      *
 100      * @return boolean success value
 101      */
 102     abstract function sendMessage($screenname, $body);
 103
 104     /**
 105      * receive a raw message
 106      * Raw IM data is taken from the incoming queue, and passed to this function.
 107      * It should parse the raw message and call handleIncoming()
 108      *
 109      * Returning false may CAUSE REPROCESSING OF THE QUEUE ITEM, and should
 110      * be used for temporary failures only. For permanent failures such as
 111      * unrecognized addresses, return true to indicate your processing has
 112      * completed.
 113      *
 114      * @param object $data raw IM data
 115      *
 116      * @return boolean true if processing completed, false for temporary failures
 117      */
 118     abstract function receiveRawMessage($data);
 119
 120     /**
 121      * get the screenname of the daemon that sends and receives message for this service
 122      *
 123      * @return string screenname of this plugin
 124      */
 125     abstract function daemonScreenname();
 126
 127     /**
 128      * get the microid uri of a given screenname
 129      *
 130      * @param string $screenname screenname
 131      *
 132      * @return string microid uri
 133      */
 134     function microiduri($screenname)
 135     {
 136         return $this->transport . ':' . $screenname;
 137     }
 138     //========================UTILITY FUNCTIONS USEFUL TO IMPLEMENTATIONS - MISC ========================\
 139
 140     /**
 141      * Put raw message data (ready to send) into the outgoing queue
 142      *
 143      * @param object $data
 144      */
 145     function enqueueOutgoingRaw($data)
 146     {
 147         $qm = QueueManager::get();
 148         $qm->enqueue($data, $this->transport . '-out');
 149     }
 150
 151     /**
 152      * Put raw message data (received, ready to be processed) into the incoming queue
 153      *
 154      * @param object $data
 155      */
 156     function enqueueIncomingRaw($data)
 157     {
 158         $qm = QueueManager::get();
 159         $qm->enqueue($data, $this->transport . '-in');
 160     }
 161
 162     /**
 163      * given a screenname, get the corresponding user
 164      *
 165      * @param string $screenname
 166      *
 167      * @return User user
 168      */
 169     function getUser($screenname)
 170     {
 171         $user_im_prefs = $this->getUserImPrefsFromScreenname($screenname);
 172         if($user_im_prefs){
 173             $user = User::getKV('id', $user_im_prefs->user_id);
 174             $user_im_prefs->free();
 175             return $user;
 176         }else{
 177             return false;
 178         }
 179     }
 180
 181     /**
 182      * given a screenname, get the User_im_prefs object for this transport
 183      *
 184      * @param string $screenname
 185      *
 186      * @return User_im_prefs user_im_prefs
 187      */
 188     function getUserImPrefsFromScreenname($screenname)
 189     {
 190         $user_im_prefs = User_im_prefs::pkeyGet(
 191             array('transport' => $this->transport,
 192                   'screenname' => $this->normalize($screenname)));
 193         if ($user_im_prefs) {
 194             return $user_im_prefs;
 195         } else {
 196             return false;
 197         }
 198     }
 199
 200     /**
 201      * given a User, get their screenname
 202      *
 203      * @param User $user
 204      *
 205      * @return string screenname of that user
 206      */
 207     function getScreenname($user)
 208     {
 209         $user_im_prefs = $this->getUserImPrefsFromUser($user);
 210         if ($user_im_prefs) {
 211             return $user_im_prefs->screenname;
 212         } else {
 213             return false;
 214         }
 215     }
 216
 217     /**
 218      * given a User, get their User_im_prefs
 219      *
 220      * @param User $user
 221      *
 222      * @return User_im_prefs user_im_prefs of that user
 223      */
 224     function getUserImPrefsFromUser($user)
 225     {
 226         $user_im_prefs = User_im_prefs::pkeyGet(
 227             array('transport' => $this->transport,
 228                   'user_id' => $user->id));
 229         if ($user_im_prefs){
 230             return $user_im_prefs;
 231         } else {
 232             return false;
 233         }
 234     }
 235     //========================UTILITY FUNCTIONS USEFUL TO IMPLEMENTATIONS - SENDING ========================\
 236     /**
 237      * Send a message to a given screenname from the site
 238      *
 239      * @param string $screenname screenname to send the message to
 240      * @param string $msg message contents to send
 241      *
 242      * @param boolean success
 243      */
 244     protected function sendFromSite($screenname, $msg)
 245     {
 246         $text = '['.common_config('site', 'name') . '] ' . $msg;
 247         $this->sendMessage($screenname, $text);
 248     }
 249
 250     /**
 251      * Send a confirmation code to a user
 252      *
 253      * @param string $screenname screenname sending to
 254      * @param string $code the confirmation code
 255      * @param User $user user sending to
 256      *
 257      * @return boolean success value
 258      */
 259     function sendConfirmationCode($screenname, $code, $user)
 260     {
 261         // TRANS: Body text for confirmation code e-mail.
 262         // TRANS: %1$s is a user nickname, %2$s is the StatusNet sitename,
 263         // TRANS: %3$s is the display name of an IM plugin.
 264         $body = sprintf(_('User "%1$s" on %2$s has said that your %3$s screenname belongs to them. ' .
 265           'If that is true, you can confirm by clicking on this URL: ' .
 266           '%4$s' .
 267           ' . (If you cannot click it, copy-and-paste it into the ' .
 268           'address bar of your browser). If that user is not you, ' .
 269           'or if you did not request this confirmation, just ignore this message.'),
 270           $user->nickname, common_config('site', 'name'), $this->getDisplayName(), common_local_url('confirmaddress', null, array('code' => $code)));
 271
 272         return $this->sendMessage($screenname, $body);
 273     }
 274
 275     /**
 276      * send a notice to all public listeners
 277      *
 278      * For notices that are generated on the local system (by users), we can optionally
 279      * forward them to remote listeners by XMPP.
 280      *
 281      * @param Notice $notice notice to broadcast
 282      *
 283      * @return boolean success flag
 284      */
 285
 286     function publicNotice($notice)
 287     {
 288         // Now, users who want everything
 289
 290         // FIXME PRIV don't send out private messages here
 291         // XXX: should we send out non-local messages if public,localonly
 292         // = false? I think not
 293
 294         foreach ($this->public as $screenname) {
 295             common_log(LOG_INFO,
 296                        'Sending notice ' . $notice->id .
 297                        ' to public listener ' . $screenname,
 298                        __FILE__);
 299             $this->sendNotice($screenname, $notice);
 300         }
 301
 302         return true;
 303     }
 304
 305     /**
 306      * broadcast a notice to all subscribers and reply recipients
 307      *
 308      * This function will send a notice to all subscribers on the local server
 309      * who have IM addresses, and have IM notification enabled, and
 310      * have this subscription enabled for IM. It also sends the notice to
 311      * all recipients of @-replies who have IM addresses and IM notification
 312      * enabled. This is really the heart of IM distribution in StatusNet.
 313      *
 314      * @param Notice $notice The notice to broadcast
 315      *
 316      * @return boolean success flag
 317      */
 318
 319     function broadcastNotice($notice)
 320     {
 321         $ni = $notice->whoGets();
 322
 323         foreach ($ni as $user_id => $reason) {
 324             $user = User::getKV($user_id);
 325             if (empty($user)) {
 326                 // either not a local user, or just not found
 327                 continue;
 328             }
 329             $user_im_prefs = $this->getUserImPrefsFromUser($user);
 330             if(!$user_im_prefs || !$user_im_prefs->notify){
 331                 continue;
 332             }
 333
 334             switch ($reason) {
 335             case NOTICE_INBOX_SOURCE_REPLY:
 336                 if (!$user_im_prefs->replies) {
 337                     continue 2;
 338                 }
 339                 break;
 340             case NOTICE_INBOX_SOURCE_SUB:
 341                 $sub = Subscription::pkeyGet(array('subscriber' => $user->id,
 342                                                    'subscribed' => $notice->profile_id));
 343                 if (empty($sub) || !$sub->jabber) {
 344                     continue 2;
 345                 }
 346                 break;
 347             case NOTICE_INBOX_SOURCE_GROUP:
 348                 break;
 349             default:
 350                 // TRANS: Exception thrown when trying to deliver a notice to an unknown inbox.
 351                 // TRANS: %d is the unknown inbox ID (number).
 352                 throw new Exception(sprintf(_('Unknown inbox source %d.'), $reason));
 353             }
 354
 355             common_log(LOG_INFO,
 356                        'Sending notice ' . $notice->id . ' to ' . $user_im_prefs->screenname,
 357                        __FILE__);
 358             $this->sendNotice($user_im_prefs->screenname, $notice);
 359             $user_im_prefs->free();
 360         }
 361
 362         return true;
 363     }
 364
 365     /**
 366      * makes a plain-text formatted version of a notice, suitable for IM distribution
 367      *
 368      * @param Notice  $notice  notice being sent
 369      *
 370      * @return string plain-text version of the notice, with user nickname prefixed
 371      */
 372
 373     protected function formatNotice(Notice $notice)
 374     {
 375         $profile = $notice->getProfile();
 376
 377         try {
 378             $parent = $notice->getParent();
 379             $orig_profile = $parent->getProfile();
 380             $nicknames = sprintf('%1$s => %2$s', $profile->nickname, $orig_profile->nickname);
 381         } catch (Exception $e) {
 382             $nicknames = $profile->nickname;
 383         }
 384
 385         return sprintf('%1$s: %2$s [%3$u]', $nicknames, $notice->content, $notice->id);
 386     }
 387     //========================UTILITY FUNCTIONS USEFUL TO IMPLEMENTATIONS - RECEIVING ========================\
 388
 389     /**
 390      * Attempt to handle a message as a command
 391      * @param User $user user the message is from
 392      * @param string $body message text
 393      * @return boolean true if the message was a command and was executed, false if it was not a command
 394      */
 395     protected function handleCommand($user, $body)
 396     {
 397         $inter = new CommandInterpreter();
 398         $cmd = $inter->handle_command($user, $body);
 399         if ($cmd) {
 400             $chan = new IMChannel($this);
 401             $cmd->execute($chan);
 402             return true;
 403         } else {
 404             return false;
 405         }
 406     }
 407
 408     /**
 409      * Is some text an autoreply message?
 410      * @param string $txt message text
 411      * @return boolean true if autoreply
 412      */
 413     protected function isAutoreply($txt)
 414     {
 415         if (preg_match('/[\[\(]?[Aa]uto[-\s]?[Rr]e(ply|sponse)[\]\)]/', $txt)) {
 416             return true;
 417         } else if (preg_match('/^System: Message wasn\'t delivered. Offline storage size was exceeded.$/', $txt)) {
 418             return true;
 419         } else {
 420             return false;
 421         }
 422     }
 423
 424     /**
 425      * Is some text an OTR message?
 426      * @param string $txt message text
 427      * @return boolean true if OTR
 428      */
 429     protected function isOtr($txt)
 430     {
 431         if (preg_match('/^\?OTR/', $txt)) {
 432             return true;
 433         } else {
 434             return false;
 435         }
 436     }
 437
 438     /**
 439      * Helper for handling incoming messages
 440      * Your incoming message handler will probably want to call this function
 441      *
 442      * @param string $from screenname the message was sent from
 443      * @param string $message message contents
 444      *
 445      * @param boolean success
 446      */
 447     protected function handleIncoming($from, $notice_text)
 448     {
 449         $user = $this->getUser($from);
 450         // For common_current_user to work
 451         global $_cur;
 452         $_cur = $user;
 453
 454         if (!$user) {
 455             $this->sendFromSite($from, 'Unknown user; go to ' .
 456                              common_local_url('imsettings') .
 457                              ' to add your address to your account');
 458             common_log(LOG_WARNING, 'Message from unknown user ' . $from);
 459             return;
 460         }
 461         if ($this->handleCommand($user, $notice_text)) {
 462             common_log(LOG_INFO, "Command message by $from handled.");
 463             return;
 464         } else if ($this->isAutoreply($notice_text)) {
 465             common_log(LOG_INFO, 'Ignoring auto reply from ' . $from);
 466             return;
 467         } else if ($this->isOtr($notice_text)) {
 468             common_log(LOG_INFO, 'Ignoring OTR from ' . $from);
 469             return;
 470         } else {
 471
 472             common_log(LOG_INFO, 'Posting a notice from ' . $user->nickname);
 473
 474             $this->addNotice($from, $user, $notice_text);
 475         }
 476
 477         $user->free();
 478         unset($user);
 479         unset($_cur);
 480         unset($message);
 481     }
 482
 483     /**
 484      * Helper for handling incoming messages
 485      * Your incoming message handler will probably want to call this function
 486      *
 487      * @param string $from screenname the message was sent from
 488      * @param string $message message contents
 489      *
 490      * @param boolean success
 491      */
 492     protected function addNotice($screenname, $user, $body)
 493     {
 494         $body = trim(strip_tags($body));
 495         $content_shortened = common_shorten_links($body);
 496         if (Notice::contentTooLong($content_shortened)) {
 497           $this->sendFromSite($screenname,
 498                               // TRANS: Message given when a status is too long. %1$s is the maximum number of characters,
 499                               // TRANS: %2$s is the number of characters sent (used for plural).
 500                               sprintf(_m('Message too long - maximum is %1$d character, you sent %2$d.',
 501                                          'Message too long - maximum is %1$d characters, you sent %2$d.',
 502                                          Notice::maxContent()),
 503                                       Notice::maxContent(),
 504                                       mb_strlen($content_shortened)));
 505           return;
 506         }
 507
 508         try {
 509             $notice = Notice::saveNew($user->id, $content_shortened, $this->transport);
 510         } catch (Exception $e) {
 511             common_log(LOG_ERR, $e->getMessage());
 512             $this->sendFromSite($from, $e->getMessage());
 513             return;
 514         }
 515
 516         common_log(LOG_INFO,
 517                    'Added notice ' . $notice->id . ' from user ' . $user->nickname);
 518         $notice->free();
 519         unset($notice);
 520     }
 521
 522     //========================EVENT HANDLERS========================\
 523
 524     /**
 525      * Register notice queue handler
 526      *
 527      * @param QueueManager $manager
 528      *
 529      * @return boolean hook return
 530      */
 531     function onEndInitializeQueueManager($manager)
 532     {
 533         $manager->connect($this->transport . '-in', new ImReceiverQueueHandler($this), 'im');
 534         $manager->connect($this->transport, new ImQueueHandler($this));
 535         $manager->connect($this->transport . '-out', new ImSenderQueueHandler($this), 'im');
 536         return true;
 537     }
 538
 539     function onStartImDaemonIoManagers(&$classes)
 540     {
 541         //$classes[] = new ImManager($this); // handles sending/receiving/pings/reconnects
 542         return true;
 543     }
 544
 545     function onStartEnqueueNotice($notice, &$transports)
 546     {
 547         $profile = Profile::getKV($notice->profile_id);
 548
 549         if (!$profile) {
 550             common_log(LOG_WARNING, 'Refusing to broadcast notice with ' .
 551                        'unknown profile ' . common_log_objstring($notice),
 552                        __FILE__);
 553         }else{
 554             $transports[] = $this->transport;
 555         }
 556
 557         return true;
 558     }
 559
 560     function onEndShowHeadElements($action)
 561     {
 562         $aname = $action->trimmed('action');
 563
 564         if ($aname == 'shownotice') {
 565
 566             $user_im_prefs = new User_im_prefs();
 567             $user_im_prefs->user_id = $action->profile->id;
 568             $user_im_prefs->transport = $this->transport;
 569
 570             if ($user_im_prefs->find() && $user_im_prefs->fetch() && $user_im_prefs->microid && $action->notice->uri) {
 571                 $id = new Microid($this->microiduri($user_im_prefs->screenname),
 572                                   $action->notice->uri);
 573                 $action->element('meta', array('name' => 'microid',
 574                                              'content' => $id->toString()));
 575             }
 576
 577         } else if ($aname == 'showstream') {
 578
 579             $user_im_prefs = new User_im_prefs();
 580             $user_im_prefs->user_id = $action->user->id;
 581             $user_im_prefs->transport = $this->transport;
 582
 583             if ($user_im_prefs->find() && $user_im_prefs->fetch() && $user_im_prefs->microid && $action->profile->profileurl) {
 584                 $id = new Microid($this->microiduri($user_im_prefs->screenname),
 585                                   $action->selfUrl());
 586                 $action->element('meta', array('name' => 'microid',
 587                                                'content' => $id->toString()));
 588             }
 589         }
 590     }
 591
 592     function onNormalizeImScreenname($transport, &$screenname)
 593     {
 594         if($transport == $this->transport)
 595         {
 596             $screenname = $this->normalize($screenname);
 597             return false;
 598         }
 599     }
 600
 601     function onValidateImScreenname($transport, $screenname, &$valid)
 602     {
 603         if($transport == $this->transport)
 604         {
 605             $valid = $this->validate($screenname);
 606             return false;
 607         }
 608     }
 609
 610     function onGetImTransports(&$transports)
 611     {
 612         $transports[$this->transport] = array(
 613             'display' => $this->getDisplayName(),
 614             'daemonScreenname' => $this->daemonScreenname());
 615     }
 616
 617     function onSendImConfirmationCode($transport, $screenname, $code, $user)
 618     {
 619         if($transport == $this->transport)
 620         {
 621             $this->sendConfirmationCode($screenname, $code, $user);
 622             return false;
 623         }
 624     }
 625
 626     function onUserDeleteRelated($user, &$tables)
 627     {
 628         $tables[] = 'User_im_prefs';
 629         return true;
 630     }
 631
 632     function onHaveImPlugin(&$haveImPlugin) {
 633         $haveImPlugin = true; // set flag true (we're loaded, after all!)
 634         return false; // stop looking
 635     }
 636
 637     function initialize()
 638     {
 639         if( ! common_config('queue', 'enabled'))
 640         {
 641             // TRANS: Server exception thrown trying to initialise an IM plugin without meeting all prerequisites.
 642             throw new ServerException(_('Queueing must be enabled to use IM plugins.'));
 643         }
 644
 645         if(is_null($this->transport)){
 646             // TRANS: Server exception thrown trying to initialise an IM plugin without a transport method.
 647             throw new ServerException(_('Transport cannot be null.'));
 648         }
 649     }
 650 }