Debian Codegraph @

lib/Rinci/resmeta.pod

raw
1 package Rinci::resmeta; # just to make PodWeaver happy
2
3 # AUTHORITY
4 # DATE
5 our $DIST = 'Rinci'; # DIST
6 # VERSION
7
8 1;
9 # ABSTRACT: Function/method result metadata
10
11 __END__
12
13 =pod
14
15 =encoding UTF-8
16
17 =head1 NAME
18
19 Rinci::resmeta - Function/method result metadata
20
21 =head1 SPECIFICATION VERSION
22
23 1.1
24
25 =head1 VERSION
26
27 This document describes version 1.1.104 of Rinci::resmeta (from Perl distribution Rinci), released on 2023-09-30.
28
29 =head1 INTRODUCTION
30
31 This document describes metadata for function/method result. This specification
32 is part of L<Rinci>. Please do a read up on it first, if you have not already
33 done so.
34
35 =head1 SPECIFICATION
36
37 There are currently several properties being used:
38
39 =head2 cmdline.*
40
41 Interpreted by L<Perinci::CmdLine>. See its documentation for more detail.
42
43 =head2 content_type
44
45 Value: str* (MIME content type)
46
47 Can be used to describe the MIME content type of result. Example enveloped
48 result (in Perl):
49
50 [200, "OK", "...", {content_type => "image/jpeg"}]
51
52 See also L</"Properties: func_content_type.*">.
53
54 Note: borrowed from HTTP.
55
56 =head2 func.*
57
58 Value: any.
59
60 These properties allow function to return extra results. Usually done to avoid
61 breaking format of existing result (to maintain API compatibility). The
62 attributes after C<func.> is up to the respective function. An example is the
63 C<get_args_from_argv()> function in the L<Perinci::Sub::GetArgs::Argv> Perl
64 module. The function returns C<$args> but from v0.26 it also wants to give hints
65 about whether or not there are missing arguments. It can do this via
66 C<func.missing_arg> result metadata. Some other examples (in Perl):
67
68 # result from check_user()
69 [200, "OK", 1, # 1 means valie
70 {
71 "func.detail" => { # detailed check result
72 last_login => '2021-01-21T01:55:40Z',
73 password_secure => 1,
74 quota_exceeded => 0,
75 },
76 }]
77
78 =head2 func_content_type.*
79
80 Value: str* (MIME content type)
81
82 Can be used to describe the MIME content type of each extra result. Example (in
83 Perl):
84
85 func.attachment => '...',
86 func_content_type.attachment => 'image/jpeg',
87
88 See also L</"Property: content_type">.
89
90 =head2 len
91
92 Value: int*
93
94 The C<len>, C<part_start> and C<part_len> properties specifies the range of data
95 when function sends partial result. Suppose your function is returning a partial
96 content of a large file where total file size is 24500000 bytes and the returned
97 content is from bytes 10000000 to 15000000, then C<len> is 24500000, C<part_len>
98 is 5000000, and C<part_start> is 10000000. When returning partial content,
99 status will be 206.
100
101 =head2 location
102
103 Value: str* (URL)
104
105 Can be used to specify that the content is elsewhere. Used in combination with
106 301 or 302 result status. Example (in Perl):
107
108 # result from a function that generates a chart
109 [301, "Moved", undef, {content_type => "image/jpeg", location=>"file:/tmp/asd9uxzw.png"}]
110
111 Note: borrowed from HTTP.
112
113 =head2 logs
114
115 Value: array[hash]
116
117 Store log of events happening to this result, stored chronologically (older
118 first). Each log should be a hash which should have at least the following keys:
119 C<time> (Unix timestamp), C<type> (string).
120
121 Normally, the first element of the log will contain information about who
122 produced the result and where/when. It has the C<type> key with the value of
123 C<create>. It should be a hash with the following keys:
124
125 =over
126
127 =item * package
128
129 Package (namespace) where this result is produced.
130
131 =item * file
132
133 File name where the result is created. Might be a relative or absolute path.
134
135 =item * line
136
137 Line number where the result is created.
138
139 =item * func
140
141 Function name where this result is produced.
142
143 =item * stack_trace
144
145 Optional, a stack trace. In Perl this can be produced by using << [caller(1),
146 caller(2), ...] >>.
147
148 =back
149
150 =head2 part_len
151
152 Value: int*
153
154 See L</"Property: len">
155
156 =head2 part_start
157
158 Value: int*
159
160 See L</"Property: len">.
161
162 =head2 perm_err
163
164 Value: bool
165
166 Indicate that error is permanent (instead of temporary/transient). This is to
167 provide a feature like that found in SMTP/POP protocol, where 4xx codes indicate
168 transient errors and 5xx permanent ones.
169
170 =head2 prev
171
172 Value: any
173
174 Store "previous result". Result MUST be enveloped. Usually useful when tracing
175 errors, especially in conjunction with C<logs>: when reporting error that
176 results from a call to another function, the original result can be set here, to
177 preserve information. See L<Perinci::Sub::Util>'s C<err()> for a convenience
178 function for this, and L<Perinci::CmdLine>'s way of displaying it.
179
180 Example:
181
182 sub f1 {
183 ...
184 if (error) { return [500, "Can't f1: blah"] }
185 ...
186 }
187
188 sub f2 {
189 ...
190 my $res = f1(...);
191 if ($res is error) { return [500, "Can't f2", undef, {prev=>$res}] }
192 ...
193 }
194
195 sub f3 {
196 ...
197 my $res = f1(...);
198 if ($res is error) { return [500, "Can't f3", undef, {prev=>$res}] }
199 }
200
201 =head2 results
202
203 Value: array*
204
205 When a function returns an error response (in particular status 207, but other
206 statuses can also use this), it can put detailed errors here. For example, a
207 function which processed 5 items wanted to report that 2 items were successfully
208 processed but the rest 3 failed:
209
210 [207, "Multistatus", undef, {
211 results => [
212 {status=>200, message=>"OK", item_id=>1},
213 {status=>403, message=>"Forbidden", item_id=>2},
214 {status=>404, message=>"Not found", item_id=>3},
215 {status=>500, message=>"Failed", item_id=>4},
216 {status=>200, message=>"OK", item_id=>5},
217 ],
218 }]
219
220 Each result is a hash to be able to store C<status>, C<message>, as well as
221 additional data like C<item_id> or whatever the function wants.
222
223 Another example, a function wants to give information on what arguments fail
224 validation:
225
226 [400, "Some arguments fail validation", undef, {
227 results => [
228 {status=>400, arg=>"name", message=>"Missing"},
229 {status=>400, arg=>"location/street", message=>"Missing"},
230 {status=>400, arg=>"age", message=>"Must be numbers only"},
231 {status=>400, arg=>"password", is_warning=>1,
232 message=>"Should be longer than 4 characters"}, # warning only
233 ],
234 }]
235
236 =head2 schema
237
238 Value: sah::schema
239
240 Describe result's schema. Has lower precedence than schema from function
241 metadata's result property.
242
243 =head2 stream
244
245 Value: bool*
246
247 If set to true, signify that result is an output stream. Usually in
248 implementations the result will be a filehandle or an object with C<getline> or
249 C<getitem> methods, where caller can then fetch data from it.
250
251 =head2 caption
252
253 Value: str*
254
255 Optional.
256
257 =head2 undo_data
258
259 Value: any
260
261 (DEPRECATED) Explained in C<undo> feature section in L<Rinci::function>.
262
263 =head1 FAQ
264
265 =head1 HOMEPAGE
266
267 Please visit the project's homepage at L<https://metacpan.org/release/Rinci>.
268
269 =head1 SOURCE
270
271 Source repository is at L<https://github.com/perlancar/perl-Rinci>.
272
273 =head1 SEE ALSO
274
275 L<Rinci>
276
277 =head1 AUTHOR
278
279 perlancar <[email protected]>
280
281 =head1 CONTRIBUTING
282
283
284 To contribute, you can send patches by email/via RT, or send pull requests on
285 GitHub.
286
287 Most of the time, you don't need to build the distribution yourself. You can
288 simply modify the code, then test via:
289
290 % prove -l
291
292 If you want to build the distribution (e.g. to try to install it locally on your
293 system), you can install L<Dist::Zilla>,
294 L<Dist::Zilla::PluginBundle::Author::PERLANCAR>,
295 L<Pod::Weaver::PluginBundle::Author::PERLANCAR>, and sometimes one or two other
296 Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond
297 that are considered a bug and can be reported to me.
298
299 =head1 COPYRIGHT AND LICENSE
300
301 This software is copyright (c) 2023, 2022, 2021, 2020, 2019, 2018, 2017, 2016, 2015, 2014, 2013, 2012 by perlancar <[email protected]>.
302
303 This is free software; you can redistribute it and/or modify it under
304 the same terms as the Perl 5 programming language system itself.
305
306 =head1 BUGS
307
308 Please report any bugs or feature requests on the bugtracker website L<https://rt.cpan.org/Public/Dist/Display.html?Name=Rinci>
309
310 When submitting a bug or request, please include a test-file or a
311 patch to an existing test-file that illustrates the bug or desired
312 feature.
313
314 =cut