Did you know ... | Search Documentation: |
![]() | http_stream.pl -- HTTP Streams |
This module realises encoding and decoding filters, implemented as Prolog streams that read/write to an underlying stream. This allows for sequences of streams acting as an in-process pipeline.
The predicate http_chunked_open/3 realises encoding and decoding of the HTTP Chunked encoding. This encoding is an obligatory part of the HTTP 1.1 specification. Messages are split into chunks, each preceeded by the length of the chunk. Chunked encoding allows sending messages over a serial link (typically a TCP/IP stream) for which the reader knows when the message is ended. Unlike standard HTTP though, the sender does not need to know the message length in advance. The protocol allows for sending short chunks. This is supported totally transparent using a flush on the output stream.
The predicate stream_range_open/3 handles the Content-length on an input stream for handlers that are designed to process an entire file. The filtering stream claims end-of-file after reading a specified number of bytes, dispite the fact that the underlying stream may be longer.
true
(default false
), the parent stream is closed
if DataStream is closed.set_stream(DataStream, buffer(line))
on the data stream to get line-buffered output. See
set_stream/2 for details. Switching buffering to false
is supported.Here is example code to write a chunked data to a stream
http_chunked_open(Out, S, []), format(S, 'Hello world~n', []), close(S).
If a stream is known to contain chunked data, we can extract this data using
http_chunked_open(In, S, []), read_stream_to_codes(S, Codes), close(S).
The current implementation does not generate chunked extensions or an HTTP trailer. If such extensions appear on the input they are silently ignored. This is compatible with the HTTP 1.1 specifications. Although a filtering stream is an excellent mechanism for encoding and decoding the core chunked protocol, it does not well support out-of-band data.
After http_chunked_open/3, the encoding of DataStream is the
same as the encoding of RawStream, while the encoding of
RawStream is octet
, the only value allowed for HTTP chunked
streams. Closing the DataStream restores the old encoding on
RawStream.
size(ContentLength)
. Closing DataStream does not close
RawStream. Options processed:
call(Closure, RawStream, BytesLeft)
when DataStream is
closed. BytesLeft is the number of bytes of the range stream
that have not been read, i.e., 0 (zero) if all data has been
read from the stream when the range is closed. This was
introduced for supporting Keep-alive in http_open/3 to
reschedule the original stream for a new request if the data
of the previous request was processed.end_of_file
if the
multipart boundary is encountered. The stream can be reset to
read the next part using multipart_open_next/1. Options:
All parts of a multipart input can be read using the following skeleton:
process_multipart(Stream) :- multipart_open(Stream, DataStream, [boundary(...)]), process_parts(DataStream). process_parts(DataStream) :- process_part(DataStream), ( multipart_open_next(DataStream) -> process_parts(DataStream) ; close(DataStream) ).
call(Hook, header, Stream)
, where Stream is a stream holding
the buffered header.call(Hook, data, Stream)
, where Stream holds the buffered
data.The stream calls Hook, adding the event and CGIStream to the closure. Defined events are:
chunked
or when the
CGI stream is closed. Typically it requests the current
header, optionally the content-length and sends the header
to the original (client) stream.The predicates cgi_property/2 and cgi_set/2 can be used to control the stream and store status info. Terms are stored as Prolog records and can thus be transferred between threads.
chunked
or none
.Keep-Alive
or close
none
.header
, data
or discarded
send_header
hook to send the reply header to the
client.Keep-Alive
or close
.chunked
or none
. Initially set to none
. When
switching to chunked
from the header
hook, it calls the
send_header
hook and if there is data queed this is send
as first chunk. Each subsequent write to the CGI stream
emits a chunk.discarded
, causing close to omit the writing the data. This
must be used for an alternate output (e.g. an error page) if the
page generator fails.chunked
encoded messages. Used
by library(http_open)
.library(http_open)
.