NAME

FastCGI::NativeCall - An implementation of FastCGI for Raku using NativeCall

SYNOPSIS

use FastCGI::NativeCall;

my $fcgi = FastCGI::NativeCall.new(path => "/tmp/fastcgi.sock", backlog => 32 );

my $count = 0;

while $fcgi.accept() {
    say $fcgi.env;
    $fcgi.header(Content-Type => "text/html");
    $fcgi.Print("{ ++$count }");
}

DESCRIPTION

FastCGI is a protocol that allows an HTTP server to communicate with a persistent application over a socket, thus removing the process startup overhead of, say, traditional CGI applications. It is supported as standard (or through supporting modules,) by most common HTTP server software (such as Apache, nginx, lighthttpd and so forth.)

This module provides a simple mechanism to create FastCGI server applications in Raku.

The FastCGI servers are single threaded, but with good support from the front end server and tuning of the configuration it can be quite efficient.

METHODS

method new

multi method new(Str :$path, Int :$backlog = 16)

The constructor must be supplied with the path where the listening Unix domain socket will be created, the location must be accessible to both your program and the host HTTP server which will be delivering the requests.

The backlog option, which defaults to 16, is the number of yet to be accepted requests that can be queued before subsequent requests receive an error, you may want to adjust this (in concert with the configuration of your host HTTP server,) to achieve an acceptable level of throughput for your application.

multi method new(Int $socket)
    multi method new(Int :$socket)

This is the original constructor which must be passed the file descriptor of an already opened and listening socket. A suitable socket can be created with the OpenSocket helper described below, or you may have got one from another source (for instance when using the Apache mod_fcgid.) The original positional form is deprecated in favour of the one with a named argument.

method Accept

method Accept(--> Int)

This blocks until a new request is received, returning a value that indicates success of zero or greater.

When this returns indicating success, the environment returned by env is populated and you may use Print to return data to the client.

You may prefer accept.

method accept

method accept(--> Bool)

This is the same as Accept above except it returns a Bool to indicate success or otherwise.

method env

method env(--> Hash)

This returns a Hash containing the "environment" as determined by the FastCGI protocol, this may be dependent on the configuration of your host HTTP server.

method header

multi method header(*%header)
    multi method header(%header)

This is a helper to output the header of the response with the correct line endings and the header/body separator from either the named header fields or from a Hash containing the header fields. If you want to return an HTTP status other than the default '200' then the Status header should be added.

method Print

method Print(Str $content)

This returns data, both headers and body content to the server to be sent to the client. This is somewhat un-sugared so if you are sending headers then each line must end in a carriage return, line feed pair and the headers must be separated from the body similarly.

method Read

method Read(Int $length --> Str)

This reads any body content from the request to the requested length, because it returns a string it will not work very nicely at all with binary data such as an image or audio file.

method close

method close()

The finishes the current request and closes the socket, after which there will be no new requests and the host HTTP server will get an error.

HELPER FUNCTIONS

These are part of the original interface and kept for compatibility. They aren't exported so must be called with the full package name.

sub OpenSocket

sub OpenSocket(Str $path, Int $backlog --> Int)

This returns the file descriptor of a listening Unix domain socket opened at the specified path and with the specified backlog. You probably want to use the named argument version of the constructor instead.

sub CloseSocket

sub CloseSocket(Int $socket-fd)

This closes the socket returned by the OpenSocket above. You may prefer to use the close method instead.