IkiWiki/Plugin/external.pm

   1 #!/usr/bin/perl
   2 # Support for external plugins written in other languages.
   3 # Communication via XML RPC a pipe.
   4 # See externaldemo for an example of a plugin that uses this.
   5 package IkiWiki::Plugin::external;
   6
   7 use warnings;
   8 use strict;
   9 use IkiWiki 2.00;
  10 use RPC::XML;
  11 use RPC::XML::Parser;
  12 use IPC::Open2;
  13 use IO::Handle;
  14
  15 my %plugins;
  16
  17 sub import { #{{{
  18         my $self=shift;
  19         my $plugin=shift;
  20         return unless defined $plugin;
  21
  22         my ($plugin_read, $plugin_write);
  23         my $pid = open2($plugin_read, $plugin_write, $plugin);
  24
  25         # open2 doesn't respect "use open ':utf8'"
  26         binmode($plugin_read, ':utf8');
  27         binmode($plugin_write, ':utf8');
  28
  29         $plugins{$plugin}={in => $plugin_read, out => $plugin_write, pid => $pid,
  30                 accum => ""};
  31
  32         rpc_call($plugins{$plugin}, "import");
  33 } #}}}
  34
  35 sub rpc_write ($$) { #{{{
  36         my $fh=shift;
  37         my $string=shift;
  38
  39         $fh->print($string."\n");
  40         $fh->flush;
  41 } #}}}
  42
  43 sub rpc_call ($$;@) { #{{{
  44         my $plugin=shift;
  45         my $command=shift;
  46
  47         # send the command
  48         my $req=RPC::XML::request->new($command, @_);
  49         rpc_write($plugin->{out}, $req->as_string);
  50
  51         # process incoming rpc until a result is available
  52         while ($_ = $plugin->{in}->getline) {
  53                 $plugin->{accum}.=$_;
  54                 while ($plugin->{accum} =~ /^\s*(<\?xml\s.*?<\/(?:methodCall|methodResponse)>)\n(.*)/s) {
  55                         $plugin->{accum}=$2;
  56                         my $r = RPC::XML::Parser->new->parse($1);
  57                         error("XML RPC parser failure: $r") unless ref $r;
  58                         if ($r->isa('RPC::XML::response')) {
  59                                 my $value=$r->value;
  60                                 if ($value->isa('RPC::XML::array')) {
  61                                         return @{$value->value};
  62                                 }
  63                                 elsif ($value->isa('RPC::XML::struct')) {
  64                                         return %{$value->value};
  65                                 }
  66                                 elsif ($value->isa('RPC::XML::fault')) {
  67                                         die $value->string;
  68                                 }
  69                                 else {
  70                                         return $value->value;
  71                                 }
  72                         }
  73
  74                         my $name=$r->name;
  75                         my @args=map { $_->value } @{$r->args};
  76
  77                         # When dispatching a function, first look in
  78                         # IkiWiki::RPC::XML. This allows overriding
  79                         # IkiWiki functions with RPC friendly versions.
  80                         my $ret;
  81                         if (exists $IkiWiki::RPC::XML::{$name}) {
  82                                 $ret=$IkiWiki::RPC::XML::{$name}($plugin, @args);
  83                         }
  84                         elsif (exists $IkiWiki::{$name}) {
  85                                 $ret=$IkiWiki::{$name}(@args);
  86                         }
  87                         else {
  88                                 error("XML RPC call error, unknown function: $name");
  89                         }
  90
  91                         my $string=eval { RPC::XML::response->new($ret)->as_string };
  92                         if ($@ && ref $ret) {
  93                                 # One common reason for serialisation to
  94                                 # fail is a complex return type that cannot
  95                                 # be represented as an XML RPC response.
  96                                 # Handle this case by just returning 1.
  97                                 $string=eval { RPC::XML::response->new(1)->as_string };
  98                         }
  99                         if ($@) {
 100                                 error("XML response serialisation failed: $@");
 101                         }
 102                         rpc_write($plugin->{out}, $string);
 103                 }
 104         }
 105
 106         return undef;
 107 } #}}}
 108
 109 package IkiWiki::RPC::XML;
 110 use Memoize;
 111
 112 sub getvar ($$$) { #{{{
 113         my $plugin=shift;
 114         my $varname="IkiWiki::".shift;
 115         my $key=shift;
 116
 117         no strict 'refs';
 118         my $ret=$varname->{$key};
 119         use strict 'refs';
 120         return $ret;
 121 } #}}}
 122
 123 sub setvar ($$$;@) { #{{{
 124         my $plugin=shift;
 125         my $varname="IkiWiki::".shift;
 126         my $key=shift;
 127
 128         no strict 'refs';
 129         my $ret=$varname->{$key}=@_;
 130         use strict 'refs';
 131         return $ret;
 132 } #}}}
 133
 134 sub inject ($@) { #{{{
 135         # Bind a given perl function name to a particular RPC request.
 136         my $plugin=shift;
 137         my %params=@_;
 138
 139         if (! exists $params{name} || ! exists $params{call}) {
 140                 die "inject needs name and call parameters";
 141         }
 142         my $sub = sub {
 143                 IkiWiki::Plugin::external::rpc_call($plugin, $params{call}, @_)
 144         };
 145         eval qq{*$params{name}=\$sub};
 146         memoize($params{name}) if $params{memoize};
 147         return 1;
 148 } #}}}
 149
 150 sub hook ($@) { #{{{
 151         # the call parameter is a function name to call, since XML RPC
 152         # cannot pass a function reference
 153         my $plugin=shift;
 154         my %params=@_;
 155
 156         my $callback=$params{call};
 157         delete $params{call};
 158
 159         IkiWiki::hook(%params, call => sub {
 160                 IkiWiki::Plugin::external::rpc_call($plugin, $callback, @_)
 161         });
 162 } #}}}
 163
 164 sub pagespec_match ($@) { #{{{
 165         # convert pagespec_match's return object into a XML RPC boolean
 166         my $plugin=shift;
 167
 168         return RPC::XML::boolean->new(0 + IkiWiki::pagespec_march(@_));
 169 } #}}}
 170
 171 1