view release on metacpan or  search on metacpan

lib/Plack/App/CGIBin/Streaming/Request.pm  view on Meta::CPAN

    $self->{on_flush}->($self);

    return 0;
}

sub finalize {
    my $self = shift;

    if (TRACE) {
        (ref(TRACE)
         ? TRACE->(finalize_start=>$self)
         : warn "finalize start $self");
    }

    $self->{on_finalize}->($self);
    if ($self->{writer}) {
        $self->{writer}->write(join '', @{$self->{_buffer}});
        $self->{writer}->close;
    } else {
        $self->_status_out(1);
    }

    if (TRACE) {
        (ref(TRACE)
         ? TRACE->(finalize_end=>$self)
         : warn "finalize end $self");
    }

    %$self=();
    bless $self, 'Plack::App::CGIBin::Streaming::Request::Demolished';
}

package                         # prevent CPAN indexing
    Plack::App::CGIBin::Streaming::Request::Demolished;
use strict;

sub AUTOLOAD {
    our $AUTOLOAD;
    die "Calling $AUTOLOAD on a demolished request.";
}

sub flush {}
sub finalize {}
sub DESTROY {}

1;

__END__

=encoding utf-8

=head1 NAME

Plack::App::CGIBin::Streaming::Request - a helper module for
Plack::App::CGIBin::Streaming

=head1 SYNOPSIS

 my $r=Plack::App::CGIBin::Streaming::Request->new(
     env => $env,               # set the PSGI environment
     responder => $responder,   # set the responder (streaming protocol)
     max_buffer => 20000,
     parse_headers => 1,
     content_type => 'text/html; charset=utf-8',
     filter_before => sub {...},
     filter_after => sub {...},
     on_status_output => sub {...},
     on_flush => sub {...},
     on_finalize => sub {...},
 );

 $r->writer=$writer;            # set the writer (streaming protocol)

 $r->notes->{key}=$value;
 $r->status=404;
 $r->content_type='text/html; charset=iso-8859-15';
 $r->parse_headers=1;

 $r->print_header(key=>$value, ...);
 $r->print_content(@content);
 $r->flush;
 warn "It's too late to set the HTTP status" if $r->status_written;

 $r->finalize;

 $r->env;                       # access the PSGI environment

=head1 DESCRIPTION

Every object of this class represents an HTTP request in the
L<Plack::App::CGIBin::Streaming> environment.

An L<Plack::App::CGIBin::Streaming> application creates the object. It is
then accessible by the actual CGI script.

To write a normal CGI script you don't need to know about this module.

=head2 Methods

The methods of this module can be categorized into several groups:

=over 4

=item * public methods to be used by CGI scripts

=item * methods or parameters mainly passed to the constructor

=item * methods to be used by the L<Plack::App::CGIBin::Streaming> system

=item * private stuff

=back

=head3 Public Methods

=over 4

=item $r-E<gt>status($status)

represents the current HTTP status of the request. You can assign new values
at any time. However, to have any effect on the HTTP response it must be
called before C<status_written> becomes true.

=item $r-E<gt>status_written

returns false if C<print_header>, C<status> or C<content_type> affect the
HTTP response seen by the client.

=item $r-E<gt>content_type($type)

represents the current C<Content-Type> of the request. You can assign new values
at any time. However, to have any effect on the HTTP response it must be

lib/Plack/App/CGIBin/Streaming/Request.pm  view on Meta::CPAN

=item on_flush

=item on_finalize

These parameters are also coderefs. All of them are called with one parameter,
the request object.

C<on_status_output> is called just before the HTTP status and the HTTP
header fields are sent to the client. It can be used to inspect the
headers one last time and to perhaps append another one.

There is one use case in particular where you might want to this hook.
Proxy servers like nginx usually also buffer your response body. But
they allow to turn that off by means of a HTTP output header.

 Plack::App::CGIBin::Streaming->new(
     root=>...,
     request_params=>[
         on_status_out=>sub {
             my $r=$_[0];

             $r->print_header('X-Accel-Buffering', 'no')
                 if $r->status==200 and $r->content_type=~m!^text/html!i;
         },
         ...
     ]
 )->to_app;

C<on_flush> is called after every flush operation.

C<on_finalize> is called before the request is finished. Actually, it's
the first step of the C<finalize> operation. At this stage you are still able
to print stuff. So, it's a good place to add a footer or similar.

=item suppress_flush

In Perl, there is a number of operations that implicitly preform flush
operations on file handles, like C<system>.

If you want complete control over when flush is issued, set this to a true
value. It does not affect C<< $r->flush >> calls or implicit flushes caused
by overflowing the output buffer (see C<max_buffer>). This flag only affects
flushes caused by the PerlIO layer. So, if true, output is buffered even if
C<$|> (autoflush) is true for the file handle.

Note, this requires the L<Plack::App::CGIBin::Streaming::IO> PerlIO layer
to be pushed onto the file handle. In the L<Plack::App::CGIBin::Streaming>
environment, this is usually the case for C<STDOUT>.

=back

=head3 Methods mainly used by the L<Plack::App::CGIBin::Streaming> system

=over 4

=item responder

=item writer

Here the responder and write callbacks are stored that implement the
PSGI streaming protocol.

=item finalize

This method is called by L<Plack::App::CGIBin::Streaming> after the compiled
CGI script returns. It prints out the remaining buffers and it makes the
request object almost unusable. So, even if you by accident save the request
object in a closure or similar, you cannot print to it. This is achieved by
reblessing the object into another class and scraping out the guts of the
object.

The only methods allowed on the reblessed object are C<flush>, C<finalize>
and C<DESTROY>.

=back

=head3 Internal Methods

=over 4

=item _buffer

=item _buflen

=item _headers

=item _header_buffer

these are just internal variables

=item _status_out

this method is called to put out the HTTP status and header fields.

=back

=head1 AUTHOR

Torsten Förtsch E<lt>torsten.foertsch@gmx.netE<gt>

=head1 COPYRIGHT

Copyright 2014 Binary.com

=head1 LICENSE

This program is free software; you can redistribute it and/or modify it
under the terms of the the Artistic License (2.0). A copy of the full
license is provided by the F<LICENSE> file in this distribution and can
be obtained at

L<http://www.perlfoundation.org/artistic_license_2_0>

=head1 SEE ALSO

=over 4

=item * L<Plack::App::CGIBin::Streaming>

=back