.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Web::Machine::Manual 3pm"
.TH Web::Machine::Manual 3pm 2024-03-08 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Web::Machine::Manual \- Learn how to use Web::Machine
.SH VERSION
.IX Header "VERSION"
version 0.17
.SH "Web::Machine IN A NUTSHELL"
.IX Header "Web::Machine IN A NUTSHELL"
The basic idea behind \f(CW\*(C`Web::Machine\*(C'\fR is that the handling of a web request
is implemented as a state machine. If you're not familiar with state machines,
think of a flowchart. We look at the request and the resource we provide and
ask questions about them. Is our service available? Is this a GET, POST, PUT,
etc.? Does the request ask for a content type our resource provides?
.PP
The result of each question leads us to the next state (or flowchart
box). Eventually we reach a point where we have a response for the
client. Since this is all built on top of Plack and
PSGI , the response consists of a status code, some
headers, and an optional body.
.PP
The best way to understand the full request/response cycle is to look at the
original Erlang webmachine state
diagram . Each diamond in that
diagram corresponds to a method that your Web::Machine::Resource subclass
can implement. The return value from your method determines what method to call
next.
.PP
However, unlike on that diagram, we often support return values beyond simple
true/false values for methods. The Web::Machine::Resource documentation
describes what each method can return.
.SH "Web::Machine and Plack"
.IX Header "Web::Machine and Plack"
\&\f(CW\*(C`Web::Machine\*(C'\fR is built on top of Plack and follows the
PSGI spec. You can mix \f(CW\*(C`Web::Machine\*(C'\fR applications
with other Plack applications using standard Plack tools like Plack::Builder.
.SS "Web::Machine and Plack Middleware"
.IX Subsection "Web::Machine and Plack Middleware"
Since \f(CW\*(C`Web::Machine\*(C'\fR implements the complete request and response
cycle, some Plack middleware is not really needed with \f(CW\*(C`Web::Machine\*(C'\fR. For
example, it wouldn't make sense to use something like
\&\f(CW\*(C`Plack::Middleware::XSLT\*(C'\fR with \f(CW\*(C`Web::Machine\*(C'\fR. \f(CW\*(C`Web::Machine\*(C'\fR implements
the full content negotiation process, so if you want to handle requests for
\&\f(CW\*(C`text/html\*(C'\fR it probably makes more sense to do this in your resources. The
benefit of doing so is that with \f(CW\*(C`Web::Machine\*(C'\fR you can easily ensure that
you return a proper \f(CW\*(C`406 Not Acceptable\*(C'\fR status for content types you
\&\fIcan't\fR handle.
.PP
There are still many pieces of Plack middleware that are useful with
\&\f(CW\*(C`Web::Machine\*(C'\fR, such as logging middleware, debugging/linting middleware,
etc.
.PP
That all said, \f(CW\*(C`Web::Machine\*(C'\fR won't break if you use an inappropriate
middleware; you'll just lose some of the benefits you get from implementing
things the \f(CW\*(C`Web::Machine\*(C'\fR way.
.SS "Bodies Must be Bytes"
.IX Subsection "Bodies Must be Bytes"
The PSGI spec requires that the body you return contain bytes, not Perl
characters. In other words, strings you return must be passed through
\&\f(CW\*(C`Encode::encode\*(C'\fR so that Perl interprets their contents as bytes.
.PP
If your data is not binary or ASCII, your resource should make sure to provide
\&\f(CWcharset_provided()\fR and \f(CWdefault_charset()\fR methods. This will make sure
that \f(CW\*(C`Web::Machine\*(C'\fR knows how to turn your response bodies into bytes.
.PP
\&\fBCAVEAT:\fR Note that currently \f(CW\*(C`Web::Machine\*(C'\fR does not provide full charset
or encoding support when the body is returned as a CODE ref. This is a bug to
be remedied in the future, but currently you are responsible for making sure
this code ref returns bytes.
.SH SUPPORT
.IX Header "SUPPORT"
bugs may be submitted through .
.SH AUTHORS
.IX Header "AUTHORS"
.IP \(bu 4
Stevan Little
.IP \(bu 4
Dave Rolsky
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
This software is copyright (c) 2016 by Infinity Interactive, Inc.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.