NAME

Plack::Middleware::PeriAHS::Respond - Send Riap request to Riap server and send the response to client

VERSION

This document describes version 0.59 of Plack::Middleware::PeriAHS::Respond (from Perl distribution Perinci-Access-HTTP-Server), released on 2015-09-03.

SYNOPSIS

 # in your app.psgi
 use Plack::Builder;

 builder {
     enable "PeriAHS::Respond";
 };

DESCRIPTION

This middleware sends Riap request ($env-{"riap.request"}>) to Riap client (Perinci::Access::* object, stored in $env-{"periahs.riap_client"}> by PeriAHS::ParseRequest middleware, thus this middleware requires the PeriAHS::ParseRequest middleware), format the result, and send it to client. This middleware is the one that sends response to client and should be put as the last middleware after all the parsing, authentication, and authorization middlewares.

The result will also be put in $env-{"riap.response"}>.

How logging works

If Riap request key loglevel is set to larger than 0 and the server chooses to support logging, the server will encode each part with:

Log message:

 "l" + <number-of-bytes> + " " + <log message>
   example: l56 [trace][Thu Apr  4 06:41:09 2013] this is a log message!

Part of Riap response:

 "r" + <number-of-bytes> + " " + <data>
  example: r9 [200,"OK"]

So the actual HTTP response body might be something like this (can be sent by the server in HTTP chunks, so that complete log messages can be displayed before the whole Riap response is received):

 l56 [trace][Thu Apr  4 06:41:09 2013] this is a log message!
 l58 [trace][Thu Apr  4 06:41:09 2013] this is another log msg!
 r9 [200,"OK"]

Developer note: additional parameter in the future can be in the form of e.g.:

 "l" + <number-of-bytes> + ("," + <additional-param> )* + " "

CONFIGURATIONS

• add_text_tips => BOOL (default: 1)

  If set to 1, then when output format is text or text-pretty, additional text tips can be added at the end of response. This helps autodiscoverability: user can just start using something like:

   % curl http://host/api/
   ...
  
   Tips:
   * To call a function, try:
       http://host/api/func1
   * Function arguments can be given via GET/POST parameters or JSON request body
   * To find out which arguments a function supports, try:
       http://host/api/func1?-riap-action=meta
   * To list subpackages, try:
       http://host/api/SubModule/
   * To find out all available actions on an entity, try:
       http://host/api/SubModule?-riap-action=actions
   * This server uses Riap protocol for great autodiscoverability, for more info:
       https://metacpan.org/module/Riap

• enable_logging => BOOL (default: 1)

  If client sends Riap request key loglevel with a value larger than 0, then server choosing to support this feature must send X-Riap-Logging: 1 HTTP response header and chunked response (as described in Riap::HTTP) with each chunk prepended (as described in Riap::HTTP and the above description). You can choose not to support this, by setting this configuration to 0.

• pass_psgi_env => BOOL (default: 0)

  Set this to true if you want your functions to have access to the PSGI environment. Functions will get it through the special argument -env.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Perinci-Access-HTTP-Server.

SOURCE

Source repository is at https://github.com/perlancar/perl-Perinci-Access-HTTP-Server.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Perinci-Access-HTTP-Server

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by perlancar@cpan.org.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Perinci::Access::HTTP::Server

perl -MCPAN -e shell
install Perinci::Access::HTTP::Server