package Rinci::resmeta; # just to make PodWeaver happy # AUTHORITY # DATE our $DIST = 'Rinci'; # DIST # VERSION 1; # ABSTRACT: Function/method result metadata __END__ =pod =encoding UTF-8 =head1 NAME Rinci::resmeta - Function/method result metadata =head1 SPECIFICATION VERSION 1.1 =head1 VERSION This document describes version 1.1.104 of Rinci::resmeta (from Perl distribution Rinci), released on 2023-09-30. =head1 INTRODUCTION This document describes metadata for function/method result. This specification is part of L. Please do a read up on it first, if you have not already done so. =head1 SPECIFICATION There are currently several properties being used: =head2 cmdline.* Interpreted by L. See its documentation for more detail. =head2 content_type Value: str* (MIME content type) Can be used to describe the MIME content type of result. Example enveloped result (in Perl): [200, "OK", "...", {content_type => "image/jpeg"}] See also L. Note: borrowed from HTTP. =head2 func.* Value: any. These properties allow function to return extra results. Usually done to avoid breaking format of existing result (to maintain API compatibility). The attributes after C is up to the respective function. An example is the C function in the L Perl module. The function returns C<$args> but from v0.26 it also wants to give hints about whether or not there are missing arguments. It can do this via C result metadata. Some other examples (in Perl): # result from check_user() [200, "OK", 1, # 1 means valie { "func.detail" => { # detailed check result last_login => '2021-01-21T01:55:40Z', password_secure => 1, quota_exceeded => 0, }, }] =head2 func_content_type.* Value: str* (MIME content type) Can be used to describe the MIME content type of each extra result. Example (in Perl): func.attachment => '...', func_content_type.attachment => 'image/jpeg', See also L. =head2 len Value: int* The C, C and C properties specifies the range of data when function sends partial result. Suppose your function is returning a partial content of a large file where total file size is 24500000 bytes and the returned content is from bytes 10000000 to 15000000, then C is 24500000, C is 5000000, and C is 10000000. When returning partial content, status will be 206. =head2 location Value: str* (URL) Can be used to specify that the content is elsewhere. Used in combination with 301 or 302 result status. Example (in Perl): # result from a function that generates a chart [301, "Moved", undef, {content_type => "image/jpeg", location=>"file:/tmp/asd9uxzw.png"}] Note: borrowed from HTTP. =head2 logs Value: array[hash] Store log of events happening to this result, stored chronologically (older first). Each log should be a hash which should have at least the following keys: C