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.

