mehari 0.2 · OCaml Package

This module provides the core abstraction, it does not depend on any platform code, and does not interact with the environment.

Types

type 'addr request

Gemini request. See Request.

type response

Gemini response. See Response.

type 'a status

Status of a Gemini response. See Status.

type mime

Mime type of a document. See Mime.

type body

Body of Gemini response. See Body.

Gemtext

module Gemtext : sig ... end

Implementation of the Gemini own native response format. Note that if a string containing line breaks (CR or CRLF) is given to functions heading, list_item and quote only the first line will be formatted and the others treated as normal text. To avoid this behavior, see Mehari.paragraph.

val paragraph : (string -> Gemtext.line) -> string -> Gemtext.t

paragraph to_gemtext str is a convenient function to transform a string containing line breaks (CR or CRLF) into a Gemtext document.

open Mehari.Gemtext

let () = assert (Mehari.paragraph quote "hello\nworld" = [ quote "hello"; quote "world" ])

Request

val uri : 'a request -> Uri.t

Request uri.

val target : 'a request -> string

Path of requested URL. For example, "/foo/bar".

val ip : 'addr request -> 'addr

Address of client sending the request.

val port : 'a request -> int

Port of client sending the request.

val sni : 'a request -> string

Server name indication TLS extension.

val query : 'a request -> string option

User uri query.

val client_cert : 'a request -> X509.Certificate.t list

User client certificates.

val param : 'a request -> int -> string

param req n retrieves the n-th path parameter of req.

raises Invalid_argument
if n is not a positive integer

raises Invalid_argument
if path does not contain any parameters in which case the program is buggy.

Response

val response : 'a status -> 'a -> response

Creates a new response with given Mehari.status.

raises Invalid_argument
if meta is more than 1024 bytes.

raises Invalid_argument
if meta starts with U+FEFF byte order mark.

val response_body : body -> mime -> response

Same as response but respond with given body and use given mime as mime type.

val response_text : string -> response

Same as response but respond with given text and use text/plain as mime type.

val response_gemtext : 
  ?charset:string ->
  ?lang:string list ->
  Gemtext.t ->
  response

Same as response but respond with given Gemtext.t and use text/gemini as mime type.

val response_raw : 
  [ `Body of string | `Full of int * string * string ] ->
  response

Creates a new raw response. Does not perform any check on validity i.e. length of header or beginning with a byte order mark U+FEFF.

`Body body: creates a response with body.
`Full (code, meta, body): creates a response with given arguments.

Status

A wrapper around Gemini status codes.

see https://gemini.circumlunar.space/docs/specification.gmi
Section "Appendix 1. Full two digit status codes" for a description of the meaning of each code.

val input : string status

val sensitive_input : string status

val success : body -> mime status

val redirect_temp : string status

val redirect_perm : string status

val temporary_failure : string status

val server_unavailable : string status

val cgi_error : string status

val proxy_error : string status

val slow_down : int status

val perm_failure : string status

val not_found : string status

val gone : string status

val proxy_request_refused : string status

val bad_request : string status

val client_cert_req : string status

val cert_not_authorised : string status

val cert_not_valid : string status

val code_of_status : 'a status -> int

code_of_status s is status code associated with status s.

Body

A note on data stream response

Mehari offers ways to keep client connections open forever and stream data in real time such as seq and stream functions when the flush parameter is specified. It is important to note that most Gemini clients do not support streaming and should be used with caution. That's why this parameter is set to false by default in all the functions that Mehari expose.

val string : string -> body

Creates a body from given string.

val gemtext : Gemtext.t -> body

Creates a body from a Gemtext.t document.

val lines : string list -> body

Creates a body from given lines. Each line is written followed by a newline (LF) character.

val page : title:string -> string -> body

page ~title content creates a simple Gemtext body of form:

# title
content

val seq : ?flush:bool -> string Stdlib.Seq.t -> body

Creates a body from a string sequence. See A note on data stream response for a description of flush parameter.

val stream : ?flush:bool -> ((string -> unit) -> unit) -> body

stream (fun consume -> ...) creates a body from a data stream. Each call to consume write the given input on socket. Useful for stream data or file chunk in real time. See A note on data stream response for a description of flush parameter.

Mime

val make_mime : ?charset:string -> string -> mime

make_mime ?charset mime creates a mime type from given charset. Charset defaults to utf-8 if mime type begins with text/.

see https://www.rfc-editor.org/rfc/rfc2046#section-4.1.2
For a description of the "charset" parameter.

val from_filename : ?charset:string -> string -> mime option

from_filename ?charset fname tries to create a mime by performing a mime lookup based on file extension of fname.

Note that mime gemini are not infered from files with .gmi extension. See https://github.com/Psi-Prod/Mehari/issues/36.

val from_content : 
  ?charset:string ->
  tree:Conan.Tree.t ->
  string ->
  mime option

from_content ?charset ~tree c tries to create a mime type by performing a mime lookup based on content c. tree is the tree used to build the MIME database.

val no_mime : mime

Represents the absence of a mime. This is a shortcut for make_mime "".

val gemini : ?charset:string -> ?lang:string list -> unit -> mime

gemini ?charset ?lang () is text/gemini; charset=...; lang=....

see https://www.rfc-editor.org/rfc/rfc2046#section-4.1.2
For a description of the "charset" parameter.

see https://www.ietf.org/rfc/bcp/bcp47.txt
For a description of the "lang" parameter.

val app_octet_stream : mime

app_octet_stream is a shortcut for application/octet-stream.

val plaintext : mime

plaintext is a shortcut for text/plain; charset=utf-8.

val text : string -> mime

text type is a shortcut for text/type; charset=utf-8.

val with_charset : mime -> string -> mime

Set charset of given mime.

IO

module type NET = sig ... end

Module type containing all environment-dependent functions.

module type FS = sig ... end

Module type containing all file system dependent functions.

Private

module Private : sig ... end

You can ignore it, unless you are porting Mehari to a new platform not supported by the existing IO backends.

package mehari