rt/html/REST/1.0/dhandler

   1 %# BEGIN BPS TAGGED BLOCK {{{
   2 %#
   3 %# COPYRIGHT:
   4 %#
   5 %# This software is Copyright (c) 1996-2009 Best Practical Solutions, LLC
   6 %#                                          <jesse@bestpractical.com>
   7 %#
   8 %# (Except where explicitly superseded by other copyright notices)
   9 %#
  10 %#
  11 %# LICENSE:
  12 %#
  13 %# This work is made available to you under the terms of Version 2 of
  14 %# the GNU General Public License. A copy of that license should have
  15 %# been provided with this software, but in any event can be snarfed
  16 %# from www.gnu.org.
  17 %#
  18 %# This work is distributed in the hope that it will be useful, but
  19 %# WITHOUT ANY WARRANTY; without even the implied warranty of
  20 %# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  21 %# General Public License for more details.
  22 %#
  23 %# You should have received a copy of the GNU General Public License
  24 %# along with this program; if not, write to the Free Software
  25 %# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  26 %# 02110-1301 or visit their web page on the internet at
  27 %# http://www.gnu.org/licenses/old-licenses/gpl-2.0.html.
  28 %#
  29 %#
  30 %# CONTRIBUTION SUBMISSION POLICY:
  31 %#
  32 %# (The following paragraph is not intended to limit the rights granted
  33 %# to you to modify and distribute this software under the terms of
  34 %# the GNU General Public License and is only of importance to you if
  35 %# you choose to contribute your changes and enhancements to the
  36 %# community by submitting them to Best Practical Solutions, LLC.)
  37 %#
  38 %# By intentionally submitting any modifications, corrections or
  39 %# derivatives to this work, or any other work intended for use with
  40 %# Request Tracker, to Best Practical Solutions, LLC, you confirm that
  41 %# you are the copyright holder for those contributions and you grant
  42 %# Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
  43 %# royalty-free, perpetual, license to use, copy, create derivative
  44 %# works based on those contributions, and sublicense and distribute
  45 %# those contributions and any derivatives thereof.
  46 %#
  47 %# END BPS TAGGED BLOCK }}}
  48 %# REST/1.0/dhandler
  49 %#
  50 <%ARGS>
  51 @id => ()
  52 $fields => undef
  53 $format => undef
  54 $content => undef
  55 </%ARGS>
  56 <%INIT>
  57 use RT::Interface::REST;
  58
  59 my $output = "";
  60 my $status = "200 Ok";
  61 my $object = $m->dhandler_arg;
  62
  63 my $name   = qr{[\w.-]+};
  64 my $list   = '(?:(?:\d+-)?\d+,)*(?:\d+-)?\d+';
  65 my $label  = '[a-zA-Z0-9@_.+-]+';
  66 my $field  = '[a-zA-Z](?:[a-zA-Z0-9_-]|\s+)*';
  67 my $labels = "(?:$label,)*$label";
  68
  69 # We must handle requests such as the following:
  70 #
  71 # 1. http://.../REST/1.0/show (with a list of object specifications).
  72 # 2. http://.../REST/1.0/edit (with a self-contained list of forms).
  73 # 3. http://.../REST/1.0/ticket/show (implicit type specification).
  74 #    http://.../REST/1.0/ticket/edit
  75 # 4. http://.../REST/1.0/ticket/nn (all possibly with a single form).
  76 #    http://.../REST/1.0/ticket/nn/history
  77 #    http://.../REST/1.0/ticket/nn/comment
  78 #    http://.../REST/1.0/ticket/nn/attachment/1
  79 #
  80 # Objects are specified by their type, and either a unique numeric ID,
  81 # or a unique name (e.g. ticket/1, queue/foo). Multiple objects of the
  82 # same type may be specified by a comma-separated list of identifiers
  83 # (e.g., user/ams,rai or ticket/1-3,5-7).
  84 #
  85 # Ultimately, we want a list of object specifications to operate upon.
  86 # The URLs in (4) provide enough information to identify an object. We
  87 # will assemble submitted information into that format in other cases.
  88 #
  89 my (@objects, $forms);
  90 my $utype;
  91
  92 if ($object eq 'show' ||                                # $REST/show
  93     (($utype) = ($object =~ m{^($name)/show$})))        # $REST/ticket/show
  94 {
  95     # We'll convert type/range specifications ("ticket/1-3,7-9/history")
  96     # into a list of singular object specifications ("ticket/1/history").
  97     # If the URL specifies a type, we'll accept only that one.
  98     foreach my $id (@id) {
  99         $id =~ s|^(?:$utype/)?|$utype/| if $utype;
 100         if (my ($type, $oids, $extra) =
 101             ($id =~ m#^($name)/($list|$labels)(?:(/.*))?$#o))
 102         {
 103             foreach my $oid (expand_list($oids)) {
 104                 if ($extra =~ m{^(?:/($name)(?:/(.*))?)?$}o) {
 105                     my ($attr, $args) = ($1, $2);
 106                     # expand transaction and attachment range specifications
 107                     # (if applicable)
 108                     my $tids;
 109                     if ($attr eq 'history' && $args =~ m#id/(\d.*)#o) {
 110                         $tids = $1;
 111                     }
 112                     if ($tids) {
 113                         push(@objects, "$type/$oid/$attr/id/$_") for expand_list($tids);
 114                     } else {
 115                         push(@objects, "$type/$oid$extra");
 116                     }
 117                 }
 118             }
 119         }
 120         else {
 121             $status = "400 Bad Request";
 122             $output = "Invalid object ID specified: '$id'";
 123             goto OUTPUT;
 124         }
 125     }
 126 }
 127 elsif ($object eq 'edit' ||                             # $REST/edit
 128     (($utype) = ($object =~ m{^($name)/edit$})))        # $REST/ticket/edit
 129 {
 130     # We'll make sure each of the submitted forms is syntactically valid
 131     # and sufficiently identifies an object to operate upon, then add to
 132     # the object list as above.
 133     my @output;
 134
 135     $forms = form_parse($content);
 136     foreach my $form (@$forms) {
 137         my ($c, $o, $k, $e) = @$form;
 138
 139         if ($e) {
 140             push @output, [ "# Syntax error.", $o, $k, $e ];
 141         }
 142         else {
 143             my ($type, $id);
 144
 145             # Look for matching types in the ID, form, and URL.
 146             $type = exists $k->{type} ? $k->{type} : $utype;
 147             $type =~ s|^(?:$utype)?|$utype/| if $utype;
 148             $type =~ s|/$||;
 149
 150             if (exists $k->{id}) {
 151                 $id = $k->{id};
 152                 $id =~ s|^(?:$type/)?|$type/| if $type;
 153
 154                 if ($id =~ m#^$name/(?:$label|\d+)(?:/.*)?#o) {
 155                     push @objects, $id;
 156                 }
 157                 else {
 158                     push @output, [ "# Invalid object ID: '$id'", $o, $k, $e ];
 159                 }
 160             }
 161             else {
 162                 push @output, [ "# No object ID specified.", $o, $k, $e ];
 163             }
 164         }
 165     }
 166     # If we saw any errors at this stage, we won't process any part of
 167     # the submitted data.
 168     if (@output) {
 169         unshift @output, [ "# Please resubmit with errors corrected." ];
 170         $status = "409 Syntax Error";
 171         $output = form_compose(\@output);
 172         goto OUTPUT;
 173     }
 174 }
 175 else {
 176     # We'll assume that this is in the correct format already. Otherwise
 177     # it will be caught by the loop below.
 178     push @objects, $object;
 179
 180     if ($content) {
 181         $forms = form_parse($content);
 182
 183         if (@$forms > 1) {
 184             $status = "400 Bad Request";
 185             $output = "You may submit only one form to this object.";
 186             goto OUTPUT;
 187         }
 188
 189         my ($c, $o, $k, $e) = @{ $forms->[0] };
 190         if ($e) {
 191             $status = "409 Syntax Error";
 192             $output = form_compose([ ["# Syntax error.", $o, $k, $e] ]);
 193             goto OUTPUT;
 194         }
 195     }
 196 }
 197
 198 # Make sure we have something to do.
 199 unless (@objects) {
 200     $status = "400 Bad Request";
 201     $output = "No objects specified.";
 202     goto OUTPUT;
 203 }
 204
 205 # Parse and validate any field specifications.
 206 my (%fields, @fields);
 207 if ($fields) {
 208     unless ($fields =~ /^(?:$field,)*$field$/) {
 209         $status = "400 Bad Request";
 210         $output = "Invalid field specification: $fields";
 211         goto OUTPUT;
 212     }
 213     @fields = map lc, split /,/, $fields;
 214     @fields{@fields} = ();
 215     unless (exists $fields{id}) {
 216         unshift @fields, "id";
 217         $fields{id} = ();
 218     }
 219 }
 220
 221 my (@comments, @output);
 222
 223 foreach $object (@objects) {
 224     my ($handler, $type, $id, $attr, $args);
 225     my ($c, $o, $k, $e) = ("", ["id"], {id => $object}, 0);
 226
 227     my $i = 0;
 228     if ($object =~ m{^($name)/(\d+|$label)(?:/($name)(?:/(.*))?)?$}o ||
 229         $object =~ m{^($name)/(new)$}o)
 230     {
 231         ($type, $id, $attr, $args) = ($1, $2, ($3 || 'default'), $4);
 232         $handler = "Forms/$type/$attr";
 233
 234         unless ($m->comp_exists($handler)) {
 235             $args = "$attr/$args";
 236             $handler = "Forms/$type/default";
 237
 238             unless ($m->comp_exists($handler)) {
 239                 $i = 2;
 240                 $c = "# Unknown object type: $type";
 241             }
 242         }
 243         elsif ($id ne 'new' && $id !~ /^\d+$/) {
 244             my $ns = "Forms/$type/ns";
 245
 246             # Can we resolve named objects?
 247             unless ($m->comp_exists($ns)) {
 248                 $i = 3;
 249                 $c = "# Objects of type $type must be specified by numeric id.";
 250             }
 251             else {
 252                 my ($n, $s) = $m->comp("Forms/$type/ns", id => $id);
 253                 if ($n <= 0) { $i = 4; $c = "# $s"; }
 254                 else         { $i = 0; $id = $n;    }
 255             }
 256         }
 257         else {
 258             $i = 0;
 259         }
 260     }
 261     else {
 262         $i = 1;
 263         $c = "# Invalid object specification: '$object'";
 264     }
 265
 266     if ($i != 0) {
 267         if ($content) {
 268             (undef, $o, $k, $e) = @{ shift @$forms };
 269         }
 270         push @output, [ $c, $o, $k ];
 271         next;
 272     }
 273
 274     unless ($content) {
 275         my $d = $m->comp($handler, id => $id, args => $args, format => $format, fields => \%fields);
 276         my ($c, $o, $k, $e) = @$d;
 277
 278         if (!$e && @$o && keys %fields) {
 279             my %lk = map { lc $_ => $_ } keys %$k;
 280             @$o = map { $lk{$_} } @fields;
 281             foreach my $key (keys %$k) {
 282                 delete $k->{$key} unless exists $fields{lc $key};
 283             }
 284         }
 285         push(@output, [ $c, $o, $k ]) if ($c || @$o || keys %$k);
 286     }
 287     else {
 288         my ($c, $o, $k, $e) = @{ shift @$forms };
 289         my $d = $m->comp($handler, id => $id, args => $args, format => $format,
 290                          changes => $k);
 291         ($c, $o, $k, $e) = @$d;
 292
 293         # We won't pass $e through to compose, trusting instead that the
 294         # handler added suitable comments for the user.
 295         if ($e) {
 296             if (@$o) {
 297                 $status = "409 Syntax Error";
 298             }
 299             else {
 300                 $status = "400 Bad Request";
 301             }
 302             push @output, [ $c, $o, $k ];
 303         }
 304         else {
 305             push @comments, $c;
 306         }
 307     }
 308 }
 309
 310 unshift(@output, [ join "\n", @comments ]) if @comments;
 311 $output = form_compose(\@output);
 312
 313 OUTPUT:
 314 $m->out("RT/".$RT::VERSION ." ".$status ."\n\n$output\n") if ($output || $status != 200);
 315 return;
 316 </%INIT>