|
| 1 | +=begin pod |
| 2 | + |
| 3 | +=head1 NAME |
| 4 | + |
| 5 | +SCGI - A SCGI library for Raku |
| 6 | + |
| 7 | +=head1 DESCRIPTION |
| 8 | + |
| 9 | +This is a simple SCGI library for Raku. |
| 10 | + |
| 11 | +It's main influences are the Perl SCGI library, and the |
| 12 | +Raku HTTP::Daemon library. |
| 13 | + |
| 14 | +It offers a bit of candy coating compared to the Perl version. |
| 15 | + |
| 16 | +By default is uses a PSGI-compliant interface, but can also handle |
| 17 | +raw HTTP responses. |
| 18 | + |
| 19 | +You don't need to create your own C<IO::Socket::INET> object. |
| 20 | +Just pass an 'addr' and 'port' attribute to the new() declaration and it'll |
| 21 | +create the object for you. |
| 22 | + |
| 23 | +=head1 USAGE |
| 24 | + |
| 25 | +The simplest (and recommended) form of usage is to use the handle() method |
| 26 | +with PSGI-compliant output. Here's an example: |
| 27 | + |
| 28 | +=begin code :lang<raku> |
| 29 | +use SCGI; |
| 30 | + |
| 31 | +my $scgi = SCGI.new( :port(8118) ); |
| 32 | + |
| 33 | +sub handler(%env) { |
| 34 | + my $name = %env<QUERY_STRING> || 'world'; |
| 35 | + my $status = '200'; |
| 36 | + my @headers = 'Content-Type' => 'text/plain'; |
| 37 | + my @body = "Hello $name\n"; |
| 38 | + @headers.push: 'Content-Length' => @body.join.encode.bytes; |
| 39 | + [ $status, @headers, @body ] |
| 40 | +} |
| 41 | + |
| 42 | +$scgi.handle: &handler; |
| 43 | +=end code |
| 44 | + |
| 45 | +There are other ways of using SCGI, such as writing your own run loop, |
| 46 | +or using a raw HTTP output instead of PSGI. Here's an example doing both: |
| 47 | + |
| 48 | +=begin code :lang<raku> |
| 49 | +use SCGI; |
| 50 | + |
| 51 | +my $scgi = SCGI.new( :port(8118), :!PSGI, :!P6SGI ); |
| 52 | +while my $connection = $scgi.accept() { |
| 53 | + my $request = $connection.request; |
| 54 | + if $request.success { |
| 55 | + my $name = $request.env<QUERY_STRING> || 'world'; |
| 56 | + my $return = "Hello $name\n"; |
| 57 | + my $len = $return.encode.bytes; |
| 58 | + my $headers = "Content-Type: text/plain\nContent-Length: $len\n"; |
| 59 | + $connection.send("$headers\n$return"); |
| 60 | + } |
| 61 | + $connection.close; |
| 62 | +} |
| 63 | +=end code |
| 64 | + |
| 65 | +Test script representing both examples can be found in the 'examples' folder. |
| 66 | + |
| 67 | +If you are serious about using SCGI for web application development, see |
| 68 | +the L<Web|https://github.com/raku-community-modules/Web/> library set, |
| 69 | +or one of the full blown frameworks built using it. |
| 70 | + |
| 71 | +=head1 CONFIGURATION |
| 72 | + |
| 73 | +=head2 nginx |
| 74 | + |
| 75 | +Make sure you compiled nginx with the SCGI plugin (it is included by default.) |
| 76 | +Then, in one of your server blocks, add a location mount: |
| 77 | + |
| 78 | +=begin code :lang<nginx> |
| 79 | +location /scgi/ { |
| 80 | + scgi_pass 127.0.0.1:8118; |
| 81 | + include scgi_params; |
| 82 | + # Optionally rewrite document URI path |
| 83 | + rewrite ^/scgi/(.*) /$1 break; |
| 84 | + # Some applications may need rewritten URI in PATH_INFO |
| 85 | + scgi_param PATH_INFO $uri; |
| 86 | +} |
| 87 | +=end code |
| 88 | + |
| 89 | +=head2 lighttpd |
| 90 | + |
| 91 | +First, make sure the SCGI library is being loaded. |
| 92 | + |
| 93 | +=begin code :lang<lighttpd> |
| 94 | +server.modules += ( "mod_scgi" ) |
| 95 | +=end code |
| 96 | + |
| 97 | +Next, set up an SCGI handler: |
| 98 | + |
| 99 | +=begin code :lang<lighttpd> |
| 100 | +scgi.server = ( |
| 101 | + "/scgi" => |
| 102 | + (( |
| 103 | + "host" => "127.0.0.1", |
| 104 | + "port" => 8118, |
| 105 | + "check-local" => "disable" |
| 106 | + )) |
| 107 | +) |
| 108 | +=end code |
| 109 | + |
| 110 | +=head2 Apache 2 with mod_scgi: |
| 111 | + |
| 112 | +Add the following line to your site config, changing the details to match your |
| 113 | +SCGI script configuration: |
| 114 | + |
| 115 | +=begin code :lang<apache> |
| 116 | +SCGIMount /scgi/ 127.0.0.1:8118 |
| 117 | +=end code |
| 118 | + |
| 119 | +=head2 Apache 2 with mod_proxy_scgi: |
| 120 | + |
| 121 | +Add the following line to your site config, changes the details to match your |
| 122 | +SCGI script configuration: |
| 123 | + |
| 124 | +=begin code :lang<apache> |
| 125 | +<Proxy *> |
| 126 | + Order deny,allow |
| 127 | + Allow from all |
| 128 | +</Proxy> |
| 129 | +ProxyPass /scgi/ scgi://localhost:8118/ |
| 130 | +=end code |
| 131 | + |
| 132 | +=head1 AUTHOR |
| 133 | + |
| 134 | +Timothy Totten |
| 135 | + |
| 136 | +=head1 COPYRIGHT AND LICENSE |
| 137 | + |
| 138 | +Copyright 2013 - 2017 Timothy Totten |
| 139 | + |
| 140 | +Copyright 2018 - 2026 Raku Community |
| 141 | + |
| 142 | +This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0. |
| 143 | + |
| 144 | +=end pod |
| 145 | + |
| 146 | +# vim: expandtab shiftwidth=4 |
0 commit comments