Giter VIP home page Giter VIP logo

plack's Introduction

NAME

Plack - Perl Superglue for Web frameworks and Web Servers (PSGI toolkit)

DESCRIPTION

Plack is a set of tools for using the PSGI stack. It contains middleware components, a reference server and utilities for Web application frameworks. Plack is like Ruby's Rack or Python's Paste for WSGI.

See PSGI for the PSGI specification and PSGI::FAQ to know what PSGI and Plack are and why we need them.

MODULES AND UTILITIES

Plack::Handler

Plack::Handler and its subclasses contains adapters for web servers. We have adapters for the built-in standalone web server HTTP::Server::PSGI, CGI, FCGI, Apache1, Apache2 and HTTP::Server::Simple included in the core Plack distribution.

There are also many HTTP server implementations on CPAN that have Plack handlers.

See Plack::Handler when writing your own adapters.

Plack::Loader

Plack::Loader is a loader to load one Plack::Handler adapter and run a PSGI application code reference with it.

Plack::Util

Plack::Util contains a lot of utility functions for server implementors as well as middleware authors.

.psgi files

A PSGI application is a code reference but it's not easy to pass code reference via the command line or configuration files, so Plack uses a convention that you need a file named app.psgi or similar, which would be loaded (via perl's core function do) to return the PSGI application code reference.

# Hello.psgi
my $app = sub {
    my $env = shift;
    # ...
    return [ $status, $headers, $body ];
};

If you use a web framework, chances are that they provide a helper utility to automatically generate these .psgi files for you, such as:

# MyApp.psgi
use MyApp;
my $app = sub { MyApp->run_psgi(@_) };

It's important that the return value of .psgi file is the code reference. See eg/dot-psgi directory for more examples of .psgi files.

plackup, Plack::Runner

plackup is a command line launcher to run PSGI applications from command line using Plack::Loader to load PSGI backends. It can be used to run standalone servers and FastCGI daemon processes. Other server backends like Apache2 needs a separate configuration but .psgi application file can still be the same.

If you want to write your own frontend that replaces, or adds functionalities to plackup, take a look at the Plack::Runner module.

Plack::Middleware

PSGI middleware is a PSGI application that wraps an existing PSGI application and plays both side of application and servers. From the servers the wrapped code reference still looks like and behaves exactly the same as PSGI applications.

Plack::Middleware gives you an easy way to wrap PSGI applications with a clean API, and compatibility with Plack::Builder DSL.

Plack::Builder

Plack::Builder gives you a DSL that you can enable Middleware in .psgi files to wrap existent PSGI applications.

Plack::Request, Plack::Response

Plack::Request gives you a nice wrapper API around PSGI $env hash to get headers, cookies and query parameters much like Apache::Request in mod_perl.

Plack::Response does the same to construct the response array reference.

Plack::Test

Plack::Test is a unified interface to test your PSGI application using standard HTTP::Request and HTTP::Response pair with simple callbacks.

Plack::Test::Suite

Plack::Test::Suite is a test suite to test a new PSGI server backend.

CONTRIBUTING

Patches and Bug Fixes

Small patches and bug fixes can be either submitted via nopaste on IRC irc://irc.perl.org/#plack or the github issue tracker. Forking on github is another good way if you intend to make larger fixes.

See also http://contributing.appspot.com/plack when you think this document is terribly outdated.

Module Namespaces

Modules added to the Plack:: sub-namespaces should be reasonably generic components which are useful as building blocks and not just simply using Plack.

Middleware authors are free to use the Plack::Middleware:: namespace for their middleware components. Middleware must be written in the pipeline style such that they can chained together with other middleware components. The Plack::Middleware:: modules in the core distribution are good examples of such modules. It is recommended that you inherit from Plack::Middleware for these types of modules.

Not all middleware components are wrappers, but instead are more like endpoints in a middleware chain. These types of components should use the Plack::App:: namespace. Again, look in the core modules to see excellent examples of these (Plack::App::File, Plack::App::Directory, etc.). It is recommended that you inherit from Plack::Component for these types of modules.

DO NOT USE Plack:: namespace to build a new web application or a framework. It's like naming your application under CGI:: namespace if it's supposed to run on CGI and that is a really bad choice and would confuse people badly.

AUTHOR

Tatsuhiko Miyagawa

COPYRIGHT

The following copyright notice applies to all the files provided in this distribution, including binary files, unless explicitly noted otherwise.

Copyright 2009-2013 Tatsuhiko Miyagawa

CORE DEVELOPERS

Tatsuhiko Miyagawa (miyagawa)

Tokuhiro Matsuno (tokuhirom)

Jesse Luehrs (doy)

Tomas Doran (bobtfish)

Graham Knop (haarg)

CONTRIBUTORS

Yuval Kogman (nothingmuch)

Kazuhiro Osawa (Yappo)

Kazuho Oku

Florian Ragwitz (rafl)

Chia-liang Kao (clkao)

Masahiro Honma (hiratara)

Daisuke Murase (typester)

John Beppu

Matt S Trout (mst)

Shawn M Moore (Sartak)

Stevan Little

Hans Dieter Pearcey (confound)

mala

Mark Stosberg

Aaron Trevena

SEE ALSO

The PSGI specification upon which Plack is based.

http://plackperl.org/

The Plack wiki: https://github.com/plack/Plack/wiki

The Plack FAQ: https://github.com/plack/Plack/wiki/Faq

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

plack's People

Contributors

abh avatar ap avatar astj avatar avar avatar chansen avatar cho45 avatar chromatic avatar dex4er avatar doy avatar fayland avatar haarg avatar hashbangperl avatar hiratara avatar ilmari avatar karenetheridge avatar kazeburo avatar kazuho avatar kes777 avatar mala avatar markstos avatar miyagawa avatar nothingmuch avatar nwellnhof avatar rafl avatar robrwo avatar theory avatar tokuhirom avatar typester avatar wchristian avatar yappo avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

plack's Issues

Plack::Builder

define DSL to quickly enable Middleware in app.psgi

use Plack::Builder;

my $app = sub { .... };

builder {
enable MiddlewareX, @Args;
enable MiddlewareY, @Args;
} $app;

or something like that.

sendfile support

12:49 miyagawa: so yuval and I talked about how to optimize file serving in some backends
12:49 miyagawa: so even pure perl backends can use Sys::Sendfile etc. to serve static files
12:49 miyagawa: $body can be an array ref or filehandle-like object, so backend implementors can check fileno $body
12:50 miyagawa: and it returns the file descriptor it MAY optimize the file serving
12:50 miyagawa: looks good, but nginx and lighttpd needs a file path instead of a fd
12:50 miyagawa: Yappo can patch nginx to get fileno instead of path but:
12:50 miyagawa: one idea is to add a new type of $body which is a reference to file path
12:51 Yappo_: http://wiki.nginx.org/NginxEmbeddedPerlModule
12:51 miyagawa: like "/path/to/foo.jpg"
12:51 Yappo_: $r->sendfile is need filename
12:51 miyagawa: but then other backend implementors need to deal with this even if it doesn't support it
12:51 miyagawa: if it doesn't support sendfile()-like optimization
12:52 miyagawa: Rack can return a body that has to_path method
12:52 miyagawa: for this thing
12:53 miyagawa: maybe the app can set the path in $env
12:53 miyagawa: or $headers
12:54 miyagawa: i like the $env approach since middleware can edit this hash ref as well
12:54 miyagawa: really wish $fh can have ->path :)
12:56 miyagawa: so maybe impl can set $env->{'psgi.can_sendfile'} = TRUE
12:56 miyagawa: and app can set $env->{'psgi.sendfile_path'} = $path

Should CGI::Emulate::PSGI append headers rather than parsing?

12:31 markstos: And this feels like a bug, but I'm not sure: If a run a simple CGI script on the command line, it prints the Content-Type header. If I run the same script through Plack and CGI::Emulate::PSGI, then it also prints 3 extra lines, which are usually supplied by the web server: "Status", "Date" and "Content-Length". Is it intentional that the Plack CGI Implementation prints these?
12:31 miyagawa: markstos: yeah i think so
12:32 miyagawa: because Emulate PSGI should be supposed to work as an app
12:32 miyagawa: Status, Date and Content-Length are something web server appends when run in CGI
12:32 markstos: You mean, an HTTP server?
12:32 miyagawa: well it's tricky but yes
12:32 miyagawa: Emulate::PSGI does something an HTTP server should do in the case of CGI
12:33 miyagawa: because it's not guaranteed the backend is really a CGI
12:33 miyagawa: well
12:33 miyagawa: there might have to be an argument whether app should set Status/Date or Impl should
12:33 miyagawa: i guess impl, but am not sure yet
12:33 markstos: Is it still OK to provide these headers if the environment is a CGI environment? I'll try to find the right docs to double check this.
12:33 miyagawa: i think it depends whethere it's running in nph mode or not
12:34 markstos: That sounds right.
12:34 miyagawa: but tokuhirom has a comment about which RFC/I-D says, doesn't he
12:34 miyagawa: yeah i think Impl should take care if it's running in nph or not
12:35 miyagawa: maybe Status shouldn't be set in the outgoing hearder, rather CGI::Emulate::PSGI should parse and turns it into the first arg of arrayref

clarify Content-Length responsibility

Some backends do not set Content-Length when the app doesn't set it, which I think is problematic. Should clarify this in the spec and also add to Plack::Test suite.

Should Plack::Response ->body DWIM?

Currently it DWIMs like

$res->body("Hello World");
$res->body($io_or_fh);
$res->body([ "Hello World" ]);
$res->body($obj_that_stringifies);

but is this a good thing? The whole if ref eq 'ARRAY' elsif ->can('getline') sounds a little uneasy. We might just want ->body_str($string) and pass through everything in ->body()?

too many open files with AnyEvent

When you write a handler that opens a file handle and then run with AnyEvent backend to benchmark with apachebench, you'll see:

EV: error in callback (ignoring): Too many open files at face.psgi line 2.

I bet the file is not closed properly.

CGI application wrapper

we can use HTTP::Request::AsCGI-like technique to wrap an existent CGI application to run under PSGI servers.

plackup -r doesn't reload the app

it refreshes the server process but $app code ref stays the same code reference, which means your application is not reloaded, which makes this reloader kind of useless.

revive Plack::Request->request_uri or alike

request_uri is now back with $env->{REQUEST_URI} but i hate the name because

$req->uri gives the normalized absolute URI and $req->request_uri gives the raw URI from /. This is confusing.

X-Sendfile stuff

We should have an unified way to indicate file path using X-Sendfile, or $env->{'psgix.sendfile'} or $body->name (using lsof.pm or such) so that:

  1. Servers (Standalone etc.) should honor when they directly send file to clients with sendfile(2)
  2. But frontend servers should strip X-Sendfile
  3. And also can configure Standalone server so it can skip file serving and front lighttpd/nginx/Apache can do sendfile
  4. What about reproxy (perlbal) though?

Idea: conditional Middleware Runner

there are some middleware components that you want to run in specific runtime conditions, such as based on IP address, cookies, User-Agent. It'd be nice if we can share those conditional rules rather than baking them in every single middleware. I think this could be a runner middleware that takes the original middleware and passes through i certain conditions.

I wonder if there are any similar attempts made in WSGI/Rack land.

Restarters is broken

  1. with Standalone, when a file is updated it just exits the whole process
  2. File::ChangeNotify depends on Moose : can we eliminate this?

discuss whether callable can be an object that does ->call

The current spec defined an application as a code reference. It would be nice if we can accept an object that ducks to ->call. It would require ALL implementors to add lines like:

$app = sub { $app->call } unless ref $app eq 'CODE';

before calling the app, or use autobox to let that happen magically. This might be a good compromise to allow PlackUp implementation and middleware developers so happy.

Create Plack::Middleware class

use overload thing is ugly.

use base qw(Plack::Middleware); sub call { ... }

and let Middleware.pm handle that thing. If we update PSGI spec to support ->call(), that overload thing should be gone.

Danga::Socket AIO fails on linux

18:08 miyagawa: 4745 at /home/comet/dev/Plack/lib/Plack/Server/Danga/Socket.pm line 209.
18:08 miyagawa: Use of uninitialized value in subroutine entry at /home/comet/dev/Plack/lib/Plack/Server/Danga/Socket.pm line 221.
18:08 miyagawa: : illegal fh argument, either not an OS file or read/write mode mismatch at /home/comet/dev/Plack/lib/Plack/Server/Danga/Socket.pm line 221.
18:09 miyagawa: んーこれ fileno わたさないとだめなんでしたっけ?
18:10 miyagawa: # Failed test at /home/comet/dev/Plack/lib/Plack/Test/Suite.pm line 157.
18:10 miyagawa: # got: '966656'
18:10 miyagawa: # expected: '2397701'

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.