Module `Mehari`Source

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

Types

Sourcetype 'addr request

Gemini request. See Request.

Sourcetype response

Gemini response. See Response.

Sourcetype 'a status

Status of a Gemini response. See Status.

Sourcetype mime

Mime type of a document. See Mime.

Sourcetype body

Body of Gemini response. See Body.

Gemtext

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

Sourceval 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

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

Request

Sourceval uri : 'a request -> Uri.t

Request uri.

Sourceval target : 'a request -> string

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

Sourceval ip : 'addr request -> 'addr

Address of client sending the request.

Sourceval port : 'a request -> int

Port of client sending the request.

Sourceval sni : 'a request -> string

Server name indication TLS extension.

Sourceval query : 'a request -> string option

User uri query.

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

User client certificates.

Sourceval 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

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

Sourceval response_body : body -> mime -> response

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

Sourceval response_text : string -> response

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

Source

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.

Source

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.

Sourceval input : string status

Sourceval sensitive_input : string status

Sourceval success : body -> mime status

Sourceval redirect_temp : string status

Sourceval redirect_perm : string status

Sourceval temporary_failure : string status

Sourceval server_unavailable : string status

Sourceval cgi_error : string status

Sourceval proxy_error : string status

Sourceval slow_down : int status

Sourceval perm_failure : string status

Sourceval not_found : string status

Sourceval gone : string status

Sourceval proxy_request_refused : string status

Sourceval bad_request : string status

Sourceval client_cert_req : string status

Sourceval cert_not_authorised : string status

Sourceval cert_not_valid : string status

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

Sourceval string : string -> body

Creates a body from given string.

Sourceval gemtext : Gemtext.t -> body

Creates a body from a Gemtext.t document.

Sourceval lines : string list -> body

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

Sourceval page : title:string -> string -> body

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

  # title
  content

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

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

Sourceval 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

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

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

Sourceval from_content : ?charset:string -> string -> mime option

from_content ?charset c tries to create a mime type by performing a mime lookup based on content c.

Sourceval no_mime : mime

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

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

Sourceval app_octet_stream : mime

app_octet_stream is a shortcut for application/octet-stream.

Sourceval plaintext : mime

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

Sourceval text : string -> mime

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

Sourceval with_charset : mime -> string -> mime

Set charset of given mime.

IO

Sourcemodule type NET = sig ... end

Module type containing all environment-dependent functions.

Sourcemodule type UNIX = sig ... end

Module type containing all UNIX-dependent functions.

Private

Sourcemodule 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

Module MehariSource