Upgrade to 4.0.10.
[usit-rt.git] / share / html / REST / 1.0 / dhandler
1 %# BEGIN BPS TAGGED BLOCK {{{
2 %#
3 %# COPYRIGHT:
4 %#
5 %# This software is Copyright (c) 1996-2013 Best Practical Solutions, LLC
6 %#                                          <sales@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   = '[^,\\/]+';
66 my $field  = RT::Interface::REST->field_spec;
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             $extra ||= '';
104             my ($attr, $args) = $extra =~ m{^(?:/($name)(?:/(.*))?)?$}o;
105             my $tids;
106             if ($attr and $attr eq 'history' and $args) {
107                 ($tids) = $args =~ m#id/(\d.*)#o;
108             }
109             # expand transaction and attachment range specifications
110             # (if applicable)
111             foreach my $oid (expand_list($oids)) {
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         else {
120             $status = "400 Bad Request";
121             $output = "Invalid object ID specified: '$id'";
122             goto OUTPUT;
123         }
124     }
125 }
126 elsif ($object eq 'edit' ||                             # $REST/edit
127     (($utype) = ($object =~ m{^($name)/edit$})))        # $REST/ticket/edit
128 {
129     # We'll make sure each of the submitted forms is syntactically valid
130     # and sufficiently identifies an object to operate upon, then add to
131     # the object list as above.
132     my @output;
133
134     $forms = form_parse($content);
135     foreach my $form (@$forms) {
136         my ($c, $o, $k, $e) = @$form;
137
138         if ($e) {
139             push @output, [ "# Syntax error.", $o, $k, $e ];
140         }
141         else {
142             my ($type, $id);
143
144             # Look for matching types in the ID, form, and URL.
145             $type = $utype || $k->{id};
146             $type =~ s|^([^/]+)/\d+$|$1| if !$utype;
147             $type =~ s|^(?:$utype)?|$utype/| if $utype;
148             $type =~ s|/$|| if $type;
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 /\s*,\s*/, $fields;
214     @fields{@fields} = ();
215     unless (exists $fields{id}) {
216         unshift @fields, "id";
217         $fields{id} = ();
218     }
219
220     # canonicalize cf-foo to cf.{foo}
221     for my $field (@fields) {
222         if ($field =~ /^(c(?:ustom)?f(?:ield)?)-(.+)/) {
223             $fields{"cf.{$2}"} = delete $fields{"$1-$2"};
224
225             # overwrite the element in @fields
226             $field = "cf.{$2}";
227         }
228     }
229 }
230
231 my (@comments, @output);
232
233 foreach $object (@objects) {
234     my ($handler, $type, $id, $attr, $args);
235     my ($c, $o, $k, $e) = ("", ["id"], {id => $object}, 0);
236
237     my $i = 0;
238     if ($object =~ m{^($name)/(\d+|$label)(?:/($name)(?:/(.*))?)?$}o ||
239         $object =~ m{^($name)/(new)$}o)
240     {
241         ($type, $id, $attr, $args) = ($1, $2, ($3 || 'default'), $4);
242         $handler = "Forms/$type/$attr";
243
244         unless ($m->comp_exists($handler)) {
245             $args = defined $args ? "$attr/$args" : $attr;
246             $handler = "Forms/$type/default";
247
248             unless ($m->comp_exists($handler)) {
249                 $i = 2;
250                 $c = "# Unknown object type: $type";
251             }
252         }
253         elsif ($id ne 'new' && $id !~ /^\d+$/) {
254             my $ns = "Forms/$type/ns";
255
256             # Can we resolve named objects?
257             unless ($m->comp_exists($ns)) {
258                 $i = 3;
259                 $c = "# Objects of type $type must be specified by numeric id.";
260             }
261             else {
262                 my ($n, $s) = $m->comp("Forms/$type/ns", id => $id);
263                 if ($n <= 0) { $i = 4; $c = "# $s"; }
264                 else         { $i = 0; $id = $n;    }
265             }
266         }
267         else {
268             $i = 0;
269         }
270     }
271     else {
272         $i = 1;
273         $c = "# Invalid object specification: '$object'";
274     }
275
276     if ($i != 0) {
277         if ($content) {
278             (undef, $o, $k, $e) = @{ shift @$forms };
279         }
280         push @output, [ $c, $o, $k ];
281         next;
282     }
283
284     unless ($content) {
285         my $d = $m->comp($handler, id => $id, args => $args, format => $format, fields => \%fields);
286         my ($c, $o, $k, $e) = @$d;
287
288         if (!$e && @$o && keys %fields) {
289             my %lk = map { lc $_ => $_ } keys %$k;
290             @$o = map { $lk{$_} } @fields;
291             foreach my $key (keys %$k) {
292                 delete $k->{$key} unless exists $fields{lc $key};
293             }
294         }
295         push(@output, [ $c, $o, $k ]) if ($c || @$o || keys %$k);
296     }
297     else {
298         my ($c, $o, $k, $e) = @{ shift @$forms };
299         my $d = $m->comp($handler, id => $id, args => $args, format => $format,
300                          changes => $k);
301         ($c, $o, $k, $e) = @$d;
302
303         # We won't pass $e through to compose, trusting instead that the
304         # handler added suitable comments for the user.
305         if ($e) {
306             if (@$o) {
307                 $status = "409 Syntax Error";
308             } 
309             else {
310                 $status = "400 Bad Request";
311             }
312             push @output, [ $c, $o, $k ];
313         }
314         else {
315             push @comments, $c;
316         }
317     }
318 }
319
320 unshift(@output, [ join "\n", @comments ]) if @comments;
321 $output = form_compose(\@output);
322
323 OUTPUT:
324 $m->out("RT/".$RT::VERSION ." ".$status ."\n\n$output\n") if ($output || $status !~ /^200/);
325 return;
326 </%INIT>