/ 
Sub-Spec-HTTP-1.0.2
/ Sub::Spec::HTTP

NAME

Sub::Spec::HTTP - Specification for sub and spec operations over HTTP

VERSION

version 1.0.2

DESCRIPTION

This is a specification for calling remote subroutines, or doing other sub-/spec-related operations over HTTP. The specification should be implemented by servers and clients written in Perl or other languages.

SPECIFICATION VERSION

1.0

TERMINOLOGIES

  • SS request

    An SS request (SS being a short for Sub::Spec) is a hash containing some keys like: command, uri, args, output_format, log_level, mark_log. See "SS REQUEST"

  • SS server

    An SS server is an HTTP server. It should parse SS request from HTTP request and then execute the SS request and return the result as HTTP response. Sub::Spec::HTTP::Server is the de facto Perl server implementation.

  • SS client

    An SS client is a library or program which sends requests to an SS server over HTTP. It should provide some transparency to its user, creating some level of illusion that the user is accessing a local sub/spec. Sub::Spec::URI::http is the de facto Perl client implementation.

SS REQUEST

An SS request is a hashref containing some predefined keys, listed below. SS server SHOULD return an HTTP 400 error code if client sends an unknown key. Not all keys are required for each request.

  • command => STR

    If not specified, default is 'call'. The list of all currently known commands is written below. A server should implement some or all of the listed commands. At the very least it MUST implement 'about' and 'call'. It SHOULD return HTTP 502 status if a command is unknown. It can implement new commands if deemed necessary.

    'about' command, to request information about the server and the request itself. For this command, no other request key is necessary. The server MUST return a hashref like this:

    {
 version        => [1, 0], # Sub::Spec::HTTP specification version
 input_formats  => [qw/json phps yaml/], # supported input formats
 output_formats => [qw/json pretty nopretty
                       yaml phps html/], # supported output formats
 # other extra keys are allowed, like ...
 server_url     => 'http://localhost:5000/api/',
 commands       => [...], # commands known by this server
}

    'call' command, to call a subroutine and return its result. For this command, request uri must be specified and contains at least module and subroutine name.

    'list_commands' command, to list known commands. No other request key is necessary.

    'list_mods' command, to list known modules. No other request key is necessary.

    'list_subs' command, to list known subroutines in a module. Request key uri must be specified and contains at least module name.

    'usage' command, to show subroutine's usage (like list of arguments and description for each). Request key uri is required and must contain at least module and subroutine name.

    'spec' command, to request spec for a subroutine. Request key uri is required and must contain at least module and subroutine name.

  • uri => STR

    Specify module and/or sub and/or arguments. See Sub::Spec::URI for more details. If invalid URI is found, server MUST return 400.

  • args => HASH (default {})

    To specify arguments. Must be a hashref, or the server MUST return 400.

  • output_format => STR

    To specify response format. Known formats are 'yaml', 'json', 'phps', 'pretty', 'simple', 'html'. A server can support more formats, but at least it MUST support 'json'.

    Server can pick default format as it deems necessary/convenient.

  • log_level => INT|STR (default 0)

    Am integer number between 0 (lowest, none) and 6 (highest, trace) or string (either "none" [0], "fatal" [1], "error" [2], "warn" [3], "info" [4], "debug" [5], "trace" [6]). Relevant only for 'call' command. When specified, a server should return log messages (e.g. produced by Log::Any) to the client in the HTTP response.

  • mark_log => BOOL (default 0)

    If set to true, prepend each log message with "L" (and response with "R") in each response chunk. Only useful/relevant when turning on log_level > 0, so clients can parse/separate log message from response.

SS SERVER

An SS server listens to HTTP requests, parses them into SS requests, and executes the SS requests for clients.

Parsing SS request from HTTP request

Server at least MUST parse SS request keys from HTTP X-SS-Req-* request headers, e.g. X-SS-Req-Command header for setting the command request key. In addition, the server MUST parse X-SS-Req-*-j- for JSON-encoded value, e.g.

X-SS-Req-Args-j-: {arg1:"val1",arg2:[1,2,3]}

should set args request key to {arg1 = "val1", arg2 => [1, 2, 3]}>.

The server MUST also accept request body for args. The server MUST accept at least body of type application/json. It can accept additional types if it wants, e.g. text/yaml or application/vnd.php.serialized.

The server can also accept SS request keys or sub arguments using other means, for example, Sub::Spec::HTTP::Server allows setting module and sub from URI path, and arguments (as well as other SS request keys, using -ss-req-* syntax) from request variables. For example:

http://HOST/api/MOD::SUBMOD/FUNC?a1=1&a2:j=[1,2]&-ss-req-command=spec

will result in the following SS request:

{
 command => 'spec',
 uri     => 'pm://MOD::SUBMOD/FUNC',
 args    => {a1=>1, a2=>[1, 2]},
}

SS CLIENT

SEE ALSO

Sub::Spec

AUTHOR

Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Steven Haryanto.

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