Web::Machine(3pm)

📦
version 0.17 · 6 versions
, in debian bookworm, ubuntu noble

💖 Web::Machine — a Perl port of Webmachine 💖

okay bestie, so this is Web::Machine, and it's a User Contributed Perl doc, sitting pretty in section 3pm of your manual pages. version? 0.17. and honestly? she ate. let's get into it 🫶

✨ SYNOPSIS ✨

use strict;
use warnings;

use Web::Machine;

{
    package HelloWorld::Resource;
    use strict;
    use warnings;

    use parent 'Web::Machine::Resource';

    sub content_types_provided { [{ 'text/html' => 'to_html' }] }

    sub to_html {
        q{<html>
            <head>
                <title>Hello World Resource</title>
            </head>
            <body>
                <h1>Hello World</h1>
            </body>
         </html>}
    }
}

Web::Machine->new( resource => 'HelloWorld::Resource' )->to_app;

like. that's the whole hello world. she's giving minimal, she's giving RESTful, she's giving iconic 💅

🌸 DESCRIPTION 🌸

Web::Machine is a RESTful web framework, and the whole vibe is that it's modeled as a state machine. you define one or more resource classes, and each resource = a single RESTful URI end point. a user, an email, whatever. and that same resource class can also be the target for POST requests when you wanna create a new user, email, etc. multitasking queen 👑

so each resource is a state machine, and every request for a resource gets handled by running that request through the state machine. that's the whole thing. that's the plot 🎀

Web::Machine is built on top of Plack, but — and this is the important part — it handles the full request and response cycle itself. no passing the aux cord around.

if you want more details on using Web::Machine in general, and on how Web::Machine and Plack interact, go read Web::Machine::Manual. it's the extended lore 🦋

this is a port of Webmachine <https://github.com/basho/webmachine> — but ngl, it's actually much closer to the Ruby version <https://github.com/seancribbs/webmachine-ruby>, with a lil bit of the JavaScript version <https://github.com/tautologistics/nodemachine> and even some of the Python version <https://github.com/benoitc/pywebmachine> thrown in for good measure. a little bit of everyone. a collaboration 🤝

you can learn a bit about Web::Machine's history from the slides for the 2012 YAPC::NA talk <https://speakerdeck.com/stevan_little/rest-from-the-trenches>. history lesson, but make it fun.

and if you wanna learn more about Webmachine itself, the SEE ALSO section at the bottom has the links. keep scrolling bestie ⬇️

💅 METHODS 💅

NOTE: this module is a Plack::Component subclass, so it follows the interface set forward by that module. respect the family lineage 👑
  • new( resource => $resource_classname, ?resource_args => $arg_list, ?tracing => 1|0, ?streaming => 1|0, ?request_class => $request_class ) — the constructor. she expects a $resource_classname, which she'll use to load and create an instance of the resource class. if that class needs any extra args, you can pass them with the resource_args parameter, and the contents of resource_args get made available to the init() method of Web::Machine::Resource. ✨

the new method can also take an optional tracing parameter, which gets passed on to Web::Machine::FSM, and an optional streaming parameter, which — if true — will run the request in a PSGI <http://plackperl.org/> streaming response. super useful if you need to run your content generation asynchronously. no blocking, no waiting, no drama 💖

the optional request_class parameter accepts the name of a module that'll be used as the request object. that module must be a class that inherits from Plack::Request. use this if you have a subclass of Plack::Request you'd like to use in your Web::Machine::Resource. custom request, custom you 💅

  • inflate_request( $env ) — takes a raw PSGI $env and inflates it into a Plack::Request instance. by default this also uses HTTP::Headers::ActionPack to inflate the headers of the request into complex objects. glow up for your headers 🎈
  • create_fsm — creates the Web::Machine::FSM object to run. it gets passed the value of the tracing constructor parameter. 🔥
  • create_resource( $request ) — creates the Web::Machine::Resource instance using the class specified in the resource constructor parameter. it passes in the $request object and calls new_response on the $request object to get a Plack::Response instance. 🫶
  • finalize_response( $response ) — give her a $response that's a Plack::Response object and she'll finalize it and return a raw PSGI response. done and dusted ⭐
  • call( $env ) — this is the call method, overridden from the Plack::Component superclass. main character behavior honestly 👑

🙈 DEBUGGING 🙈

if you set the WM_DEBUG environment variable to 1, we'll print out information about the path taken through the state machine to STDERR. like a little breadcrumb trail of what your request did. it's giving detective 🕵️

if you set WM_DEBUG to diag, then the debugging information gets printed using Test::More's diag() sub instead. fancy ✨

🌈 SEE ALSO 🌈

the links, as promised, bestie:

🐛 SUPPORT 🐛

found a bug? first of all, relatable. second of all, bugs may be submitted through <https://github.com/houseabsolute/webmachine-perl/issues>. go off, report it 💜

👑 AUTHORS 👑

  • Stevan Little <stevan@cpan.org>
  • Dave Rolsky <autarch@urth.org>

🧚 CONTRIBUTORS 🧚

the whole group chat, in alphabetical-ish order:

  • Andreas Marienborg <andreas.marienborg@gmail.com>
  • Andrew Nelson <anelson@cpan.org>
  • Arthur Axel 'fREW' Schmidt <frioux@gmail.com>
  • Carlos Fernando Avila Gratz <cafe@q1software.com>
  • Fayland Lam <fayland@gmail.com>
  • George Hartzell <hartzell@alerce.com>
  • Gregory Oschwald <goschwald@maxmind.com>
  • Jesse Luehrs <doy@tozt.net>
  • John SJ Anderson <genehack@genehack.org>
  • Mike Raynham <enquiries@mikeraynham.co.uk>
  • Nathan Cutler <ncutler@suse.cz>
  • Olaf Alders <olaf@wundersolutions.com>
  • Stevan Little <stevan.little@gmail.com>
  • Thomas Sibley <tsibley@cpan.org>

this software is copyright (c) 2016 by Infinity Interactive, Inc.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. free as in freedom, free as in slay 🦋

and that's the page, bestie!! this doc came to you courtesy of perl v5.34.0, dated 2022-07-03, from Web::Machine(3pm) — mwah, go build something RESTful 💖✨🎀

📦 where this page comes from