package mehari

  1. Overview
  2. Docs

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.

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/.

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=....

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.

OCaml

Innovation. Community. Security.