NAME
    HTTP::Handy - A handy HTTP/1.0 server for Perl 5.5.3 and later

VERSION
    1.00

SYNOPSIS
        use HTTP::Handy;

        my $app = sub {
            my $env = shift;
            return [200, ['Content-Type', 'text/plain'], ['Hello, World!']];
        };

        HTTP::Handy->run(app => $app, port => 8080);

DESCRIPTION
    HTTP::Handy is a single-file, zero-dependency HTTP/1.0 server for Perl.
    It implements a subset of the PSGI specification and is designed for
    personal use, local tools, and rapid development.

    Not intended for production or internet-facing deployment.

    The goals of the project are simplicity and portability. The entire
    implementation fits in one file with no installation step beyond copying
    it into your project directory.

REQUIREMENTS
    Perl     : 5.5.3 or later (all versions, all platforms)
    OS       : Any (Windows, Unix, macOS, and others)
    Modules  : Core only -- IO::Socket, POSIX, Carp
    Model    : Single process, single thread

    No CPAN modules are required.
    No C compiler or external library is needed.

INSTALLATION
    Manual (no build tools required):

        cp lib/HTTP/Handy.pm /path/to/your/project/

    Via CPAN:

        cpan HTTP::Handy
        cpanm HTTP::Handy

    Via perl Makefile.PL:

        perl Makefile.PL
        make
        make test
        make install

DEMO
    Run directly to start a self-contained demo server:

        perl lib/HTTP/Handy.pm
        perl lib/HTTP/Handy.pm 9090

    Then open http://localhost:8080/ in your browser.

    The demo provides three pages:
      /        Top page with a GET form and a POST form
      /echo    Echoes parameters back in a table
      /info    Shows the full PSGI $env hash (useful for debugging)

FEATURES
    - HTTP/1.0, GET and POST
    - PSGI subset compatible interface
    - Static file serving with automatic MIME type detection
    - Path traversal protection
    - URL decode and query string parsing
    - Convenience response builders: response_html, response_text,
      response_json, response_redirect
    - Access log to STDERR with timestamp
    - App exceptions caught and returned as 500 responses
    - Works as both a module (use HTTP::Handy) and a standalone script

PSGI SUBSET
    Request environment ($env):

      REQUEST_METHOD    "GET" or "POST"
      PATH_INFO         URL path (e.g. "/index.html")
      QUERY_STRING      Query string, without leading "?"
      SERVER_NAME       Host name
      SERVER_PORT       Port number
      CONTENT_TYPE      Content-Type of POST request
      CONTENT_LENGTH    Content-Length of POST body
      HTTP_*            Request headers (uppercased, hyphens to underscores)
      psgi.input        HTTP::Handy::Input object (read POST body via ->read)
      psgi.errors       \*STDERR
      psgi.url_scheme   "http"

    Response format:

      [$status_code, \@headers, \@body]

      $status_code  integer (e.g. 200, 404)
      \@headers     flat array: ['Content-Type', 'text/html', ...]
      \@body        array of strings, joined and sent as response body

LIMITATIONS
    - HTTP/1.0 only (no Keep-Alive, no HTTP/1.1, no HTTP/2)
    - GET and POST only (HEAD, PUT, DELETE etc. return 405)
    - Single process, single thread (one request at a time)
    - No HTTPS (use a reverse proxy such as Caddy for TLS)
    - No chunked transfer encoding
    - POST body fully buffered in memory (max 10 MB)
    - No cookie or session management

HTTPS NOTE
    HTTP::Handy does not support HTTPS. For local use on 127.0.0.1 or
    localhost, modern browsers do not show HTTPS warnings. For LAN or
    internet use, place a reverse proxy in front of HTTP::Handy:

        Browser <--HTTPS--> Caddy/nginx/Apache <--HTTP--> HTTP::Handy

TESTING
    Run the test suite:

        make test

    Or directly with prove:

        prove -l t/

    Network tests (t/03-server.t, t/04-psgi-env.t) start a real HTTP server
    and connect to it via IO::Socket on the loopback address.

    On Unix the server child is started with fork().
    On Windows the server is written to a temp file and launched with
    system(1, ...), which is a Win32 Perl built-in for asynchronous process
    creation.  Both paths exercise identical test cases.

    All tests pass on CPAN Testers across Windows, Linux, macOS, and BSD.

SEE ALSO
    PSGI    - The Perl Web Server Gateway Interface specification
    Plack   - Full-featured PSGI toolkit (requires Perl 5.8+)
    HTTP::Server::Simple - Another minimal HTTP server for Perl

AUTHOR
    ina, CPAN

LICENSE
    This module is free software. It may be used, redistributed and/or
    modified under the same terms as Perl itself.

    See http://www.perl.com/perl/misc/Artistic.html