/ 
Sub-Spec-HTTP-1.0.0
/ Sub::Spec::HTTP

NAME

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

VERSION

version 1.0.0

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, sub, module, args, resp_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::HTTP::Client 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

    Always required. Default command is 'call'. The list of all currently known commands are written below. A server should implement some or all of the listed commands. 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. For this command, no other request key is necessart. 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
}

    'call' command, to call a subroutine and return its result. For this command, at least 'module' and 'sub' are required. 'args' is also required, but will default to {} (empty hash) if not specified.

    '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 'module' is required.

    'usage' command, to show subroutine's usage (like list of arguments and description for each). Request keys 'sub' and 'module' are required.

    'spec' command, to request spec for a subroutine. Request keys 'sub' and 'module' are required.

  • module => STR

    To specify module name. All groups of nonalphanumeric characters SHOULD be converted to server's language, for example: Foo.Bar_Baz should be converted to Foo::Bar_Baz by the Perl server. If invalid module name is specified, server MUST return HTTP 400.

  • sub => STR

    To specify subroutine name. If invalid subroutine name is specified, 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', 'php', '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, parsing them into SS requests, and execute 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?arg1=val1&arg2:j=[1,2]&-ss-req-command=spec

will result in the following SS request:

{
 command => 'spec',
 module  => 'MOD::SUBMOD',
 sub     => 'FUNC',
 args    => {arg1=>'val1', arg2=>[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.