Module `Tiny_httpd_stream`Source

Byte streams.

Streams are used to represent a series of bytes that can arrive progressively. For example, an uploaded file will be sent as a series of chunks.

These used to live in Tiny_httpd but are now in their own module.

since 0.12

Sourcetype hidden

Type used to make t unbuildable via a record literal. Use make instead.

Sourcetype t = {

mutable bs : bytes;
(*
The bytes
*)
mutable off : int;
(*
Beginning of valid slice in bs
*)
mutable len : int;
(*
Length of valid slice in bs. If len = 0 after a call to fill, then the stream is finished.
*)
fill_buf : unit -> unit;
(*
See the current slice of the internal buffer as bytes, i, len, where the slice is bytes[i] .. [bytes[i+len-1]]. Can block to refill the buffer if there is currently no content. If len=0 then there is no more data.
*)
consume : int -> unit;
(*
Consume n bytes from the buffer. This should only be called with n <= len.
*)
close : unit -> unit;
(*
Close the stream.
*)
_rest : hidden;
(*
Use make to build a stream.
*)

}

A buffered stream, with a view into the current buffer (or refill if empty), and a function to consume n bytes.

The point of this type is that it gives the caller access to its internal buffer (bs, with the slice off,len). This is convenient for things like line reading where one needs to peek ahead.

Some core invariant for this type of stream are:

off,len delimits a valid slice in bs (indices: off, off+1, … off+len-1)
if fill_buf() was just called, then either len=0 which indicates the end of stream; or len>0 and the slice contains some data.

To actually move forward in the stream, you can call consume n to consume n bytes (where n <= len). If len gets to 0, calling fill_buf() is required, so it can try to obtain a new slice.

To emulate a classic OCaml reader with a read: bytes -> int -> int -> int function, the simplest is:

let read (self:t) buf offset max_len : int =
  self.fill_buf();
  let len = min max_len self.len in
  if len > 0 then (
    Bytes.blit self.bs self.off buf offset len;
    self.consume len;
  );
  len

Sourceval close : t -> unit

Close stream

Sourceval empty : t

Stream with 0 bytes inside

Sourceval of_input : ?buf_size:int -> Tiny_httpd_io.Input.t -> t

Make a buffered stream from the given channel.

since 0.14

Sourceval of_chan : ?buf_size:int -> in_channel -> t

Make a buffered stream from the given channel.

Sourceval of_chan_close_noerr : ?buf_size:int -> in_channel -> t

Same as of_chan but the close method will never fail.

Sourceval of_fd : ?buf_size:int -> Unix.file_descr -> t

Make a buffered stream from the given file descriptor.

Sourceval of_fd_close_noerr : ?buf_size:int -> Unix.file_descr -> t

Same as of_fd but the close method will never fail.

Sourceval of_bytes : ?i:int -> ?len:int -> bytes -> t

A stream that just returns the slice of bytes starting from i and of length len.

Sourceval of_string : string -> t

Sourceval iter : (bytes -> int -> int -> unit) -> t -> unit

Iterate on the chunks of the stream

since 0.3

Sourceval to_chan : out_channel -> t -> unit

Write the stream to the channel.

since 0.3

Sourceval to_chan' : Tiny_httpd_io.Output.t -> t -> unit

Write to the IO channel.

since 0.14

Sourceval to_writer : t -> Tiny_httpd_io.Writer.t

Turn this stream into a writer.

since 0.14

Source

val make : 
  ?bs:bytes ->
  ?close:(t -> unit) ->
  consume:(t -> int -> unit) ->
  fill:(t -> unit) ->
  unit ->
  t

make ~fill () creates a byte stream.

parameter fill
is used to refill the buffer, and is called initially.

parameter close
optional closing.

parameter init_size
size of the buffer.

Sourceval with_file : ?buf_size:int -> string -> (t -> 'a) -> 'a

Open a file with given name, and obtain an input stream on its content. When the function returns, the stream (and file) are closed.

Sourceval read_line : ?buf:Tiny_httpd_buf.t -> t -> string

Read a line from the stream.

parameter buf
a buffer to (re)use. Its content will be cleared.

Sourceval read_all : ?buf:Tiny_httpd_buf.t -> t -> string

Read the whole stream into a string.

parameter buf
a buffer to (re)use. Its content will be cleared.

Source

val limit_size_to : 
  close_rec:bool ->
  max_size:int ->
  too_big:(int -> unit) ->
  t ->
  t

Sourceval read_chunked : ?buf:Tiny_httpd_buf.t -> fail:(string -> exn) -> t -> t

Convert a stream into a stream of byte chunks using the chunked encoding. The size of chunks is not specified.

parameter buf
buffer used for intermediate storage.

parameter fail
used to build an exception if reading fails.

Source

val read_exactly : 
  close_rec:bool ->
  size:int ->
  too_short:(int -> unit) ->
  t ->
  t

read_exactly ~size bs returns a new stream that reads exactly size bytes from bs, and then closes.

parameter close_rec
if true, closing the resulting stream also closes bs

parameter too_short
is called if bs closes with still n bytes remaining

Sourceval output_chunked : ?buf:Tiny_httpd_buf.t -> out_channel -> t -> unit

Write the stream into the channel, using the chunked encoding.

parameter buf
optional buffer for chunking (since 0.14)

Source

val output_chunked' : 
  ?buf:Tiny_httpd_buf.t ->
  Tiny_httpd_io.Output.t ->
  t ->
  unit

Write the stream into the channel, using the chunked encoding.

since 0.14

package tiny_httpd

Module Tiny_httpd_streamSource

Module `Tiny_httpd_stream`Source