unikernel/duniverse/ocaml-uri/lib/uri.mli

@@ -0,0 +1,304 @@
+(*
+ * Copyright (c) 2012-2013 Anil Madhavapeddy <anil@recoil.org>
+ *
+ * Permission to use, copy, modify, and distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ *
+ *)
+
+(** Uniform Resource Identifier handling that is RFC3986-compliant. *)
+
+(** A single URI that is a compact sequence of characters that identifies
+    an abstract or physical resource. *)
+type t
+
+type component = [
+    `Scheme
+  | `Authority
+  | `Userinfo (** subcomponent of authority in some schemes *)
+  | `Host (** subcomponent of authority in some schemes *)
+  | `Path
+  | `Query
+  | `Query_key
+  | `Query_value
+  | `Fragment
+  | `Generic
+  | `Custom of (component * string * string) (* (component * safe chars * unsafe chars) *)
+  ]
+
+(** For pct encoding customization when converting a URI to a string. *)
+type pct_encoder
+
+(** {2 Core functionality } *)
+
+(** The empty (zero length) URI reference. Useful for constructing
+    URIs piece-by-piece. *)
+val empty : t
+
+(** Comparator ordering by host, scheme, port, userinfo, path, query,
+    and finally fragment. Designed to produce a reasonable sort order. *)
+val compare : t -> t -> int
+
+(** [equal a b] is [compare a b = 0]. *)
+val equal : t -> t -> bool
+
+(** Percent-encode a string. The [component] argument defaults to `Path *)
+val pct_encode : ?scheme:string -> ?component:component -> string -> string
+
+(** Construct a pct_encoder. *)
+val pct_encoder :
+  ?scheme:component ->
+  ?userinfo:component ->
+  ?host:component ->
+  ?path:component ->
+  ?query_key:component ->
+  ?query_value:component ->
+  ?fragment:component ->
+  unit ->
+  pct_encoder
+
+(** Percent-decode a percent-encoded string *)
+val pct_decode : string -> string
+
+(** Parse a URI string literal into a URI structure. A bare string will be
+    interpreted as a path; a string prefixed with `//` will be interpreted as a
+    host.
+*)
+val of_string : string -> t
+
+(** Convert a URI structure into a percent-encoded URI string *)
+val to_string : ?pct_encoder:pct_encoder -> t -> string
+
+(** Resolve a URI against a default scheme and base URI *)
+val resolve : string -> t -> t -> t
+
+(** Canonicalize a URI according to Sec 6.2.3 "Scheme-Based
+    Normalization". This transform is more aggressive than the
+    standard URI-generic normalization automatically done. In
+    particular, HTTP(S) URIs with empty path components will have
+    their path components set to "/". Some applications like web
+    servers may rely on the distinction between a path-less and a
+    root-path URI to distinguish request URIs (e.g. OPTIONS * vs
+    OPTIONS /).
+
+    @see <https://tools.ietf.org/html/rfc3986#section-6.2.3> RFC 3986.6.2.3
+*)
+val canonicalize : t -> t
+
+(** Make a URI from supplied components. If userinfo or port are
+    supplied without host, an empty host is added. If path is supplied
+    and userinfo, host, or port is also supplied, path is made
+    absolute but not resolved. *)
+val make : ?scheme:string -> ?userinfo:string -> ?host:string ->
+  ?port:int -> ?path:string -> ?query:(string * string list) list ->
+  ?fragment:string -> unit -> t
+
+(** Functional update for a URI using the supplied components.  If a component
+    is unspecified then it will be unchanged.  If a component is supplied as
+    [None] then the component will be removed in the returned URI.  If a
+    component is supplied as [Some x] then [x] will be added if it does not
+    exist in the source URI or replaced if it does exist. *)
+val with_uri : ?scheme:string option -> ?userinfo:string option ->
+  ?host:string option -> ?port:int option -> ?path:string option ->
+  ?query:(string * string list) list option -> ?fragment:string option -> t -> t
+
+(** {2 Query functions }
+
+    The query string API attempts to accommodate conventional query
+    string representations (i.e. [?key0=value0&key1=value1]) while
+    maximally exposing any meaning in those representations. For
+    example, it is not necessarily the case that [/] and [/?] are
+    equivalent to a web server. In the former case, we observe a zero
+    query string whereas in the latter case, we observe a query string
+    with a single key, [""] and a zero value. Compare this with [/?=]
+    which has a single key and a single empty value,
+    [""]. Additionally, some query functions return lists of values
+    for a key. These list values are extracted from a {b single} key
+    with a comma-separated value list. If a query string has multiple
+    identical keys, you must use {! query} to retrieve the entirety of
+    the structured query string.
+*)
+
+(** Get a query string from a URI *)
+val query : t -> (string * string list) list
+
+(** Get a verbatim query string from a URI. If the provenance of the
+    URI is a string and its query component has not been updated, this
+    is the literal query string as parsed. Otherwise, this is the
+    composition of {!query} and {!encoded_of_query} *)
+val verbatim_query : ?pct_encoder:pct_encoder -> t -> string option
+
+(** Make a percent-encoded query string from percent-decoded query tuple *)
+val encoded_of_query :
+  ?scheme:string ->
+  ?pct_encoder:pct_encoder ->
+  (string * string list) list ->
+  string
+
+(** Parse a percent-encoded query string into a percent-decoded query tuple *)
+val query_of_encoded : string -> (string * string list) list
+
+(** Replace the query URI with the supplied list.
+    Input URI is not modified
+*)
+val with_query : t -> (string * string list) list -> t
+
+(** Replace the query URI with the supplied singleton query list.
+    Input URI is not modified
+*)
+val with_query' : t -> (string * string) list -> t
+
+(** [get_query_param' q key] returns the list of values for the
+    [key] parameter in query [q].  Note that an empty list is not the
+    same as a [None] return value.  For a query [foo], the mapping is:
+    - [/] returns None
+    - [/?foo] returns Some []
+    - [/?foo=] returns [Some [""]]
+    - [/?foo=bar] returns [Some ["bar"]]
+    - [/?foo=bar,chi] returns [Some ["bar","chi"]]
+
+    Query keys can be duplicated in the URI, in which case the first
+    one is returned.  If you want to resolve duplicate keys, obtain
+    the full result set with {! query } instead.
+*)
+val get_query_param' : t -> string -> string list option
+
+(** [get_query_param q key] returns the value found for a [key] in
+     query [q].  If there are multiple values for the key, then the
+     first one is returned. *)
+val get_query_param: t -> string -> string option
+
+(** Add a query parameter to the input query URI.
+    Input URI is not modified
+*)
+val add_query_param : t -> (string * string list) -> t
+
+(** Add a query parameter to the input singleton query URI.
+    Input URI is not modified
+*)
+val add_query_param' : t -> (string * string) -> t
+
+(** Add a query parameter list to the input query URI.
+    Input URI is not modified
+*)
+val add_query_params : t -> (string * string list) list -> t
+
+(** Add a query singleton parameter list to the input query URI.
+    Input URI is not modified
+*)
+val add_query_params' : t -> (string * string) list -> t
+
+(** Remove a query key from the input query URI.
+    Input URI is not modified, and no error is generated if the
+    key does not already exist in the URI.
+*)
+val remove_query_param : t -> string -> t
+
+(** {2 Component getters and setters } *)
+
+(** Get the encoded path component of a URI *)
+val path : ?pct_encoder:pct_encoder -> t -> string
+
+(** Get the encoded path and query components of a URI *)
+val path_and_query : t -> string
+
+(** Replace the path URI with the supplied encoded path.
+    If a host is present in the supplied URI, the path is made absolute but not
+    resolved. If the path is empty, the path component is removed.
+    Input URI is not modified *)
+val with_path : t -> string -> t
+
+(** Get the scheme component of a URI *)
+val scheme : t -> string option
+
+(** Replace the scheme portion of the URI with the supplied [scheme].
+    Input URI is not modified *)
+val with_scheme : t -> string option -> t
+
+(** Get the userinfo component of a URI *)
+val userinfo : ?pct_encoder:pct_encoder -> t -> string option
+
+(** Replace the userinfo portion of the URI with the supplied [string option].
+    If no host is present in the supplied URI, an empty host is added.
+    Input URI is not modified. *)
+val with_userinfo : t -> string option -> t
+
+(** Get the username component of a URI *)
+val user : t -> string option
+
+(** Get the password component of a URI *)
+val password : t -> string option
+
+(** Replace the password portion of the URI with the supplied [string option].
+    If no host is present in the supplied URI, an empty host is added.
+    Input URI is not modified.
+*)
+val with_password : t -> string option -> t
+
+(** Get the host component of a URI *)
+val host : t -> string option
+
+(** Replace the host component of the URI.
+    Input URI is not modified. *)
+val with_host: t -> string option -> t
+
+(** Get the host component of a URI, with a default supplied if one is
+    not present *)
+val host_with_default: ?default:string -> t -> string
+
+(** Get the port component of a URI *)
+val port : t -> int option
+
+(** Replace the port component of the URI with the supplied port.
+    If no host is present in the supplied URI, an empty host is added.
+    Input URI is not modified. *)
+val with_port : t -> int option -> t
+
+(** Get the fragment component of a URI *)
+val fragment : t -> string option
+
+(** Replace the fragment component of a URI with the supplied fragment.
+    Input URI is not modified *)
+val with_fragment : t -> string option -> t
+
+(** {2 Formatters } *)
+
+(**  [pp ppf t] will output a human readable version of the Uri [t]
+    to the formatter [ppf] *)
+val pp : Format.formatter -> t -> unit [@@ocaml.toplevel_printer]
+
+(**  [pp_hum] is now an alias for the {!pp} function. *)
+val pp_hum : Format.formatter -> t -> unit
+
+module Parser : sig
+  val ipv6 : string Angstrom.t
+  val uri_reference : t Angstrom.t
+end
+
+(** Specializations for HTTP and HTTPS schemes as per RFC9110 *)
+module Absolute_http : sig
+  type uri := t
+  type t
+
+  val of_uri : uri -> (t, [ `Msg of string ]) result
+  val to_uri : t -> uri
+
+  val of_string : string -> t
+  val to_string : ?pct_encoder:pct_encoder -> t -> string
+
+  val make : scheme:[ `Http | `Https ]-> host:string ->
+    ?userinfo:string -> ?port:int -> ?path:string ->
+    ?query:(string * string list) list -> ?fragment:string -> unit -> t
+
+  val host : t -> string
+  val scheme : t -> [`Http | `Https]
+end