Http is the CLI entry point. It is not meant to be used directly in OCaml code. Use Http_ instead.

include module type of Http_

Trusted TLS certificate authorities

For Windows and macOS, the operating system TLS shared security libraries are used.

For all other operating systems, the CA certificates are searched in the following files and directories adopted from the Go language:

  • "/etc/ssl/certs/ca-certificates.crt" // Debian/Ubuntu/Gentoo etc.
  • "/etc/pki/tls/certs/ca-bundle.crt" // Fedora/RHEL 6
  • "/etc/ssl/ca-bundle.pem" // OpenSUSE
  • "/etc/pki/tls/cacert.pem" // OpenELEC
  • "/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem" // CentOS/RHEL 7
  • "/etc/ssl/cert.pem" // Alpine Linux
  • All files in "/etc/ssl/certs" // SLES10/SLES11
  • All files in "/etc/pki/tls/certs" // Fedora/RHEL
  • (Android only) All files in "/system/etc/security/cacerts" // Android system roots
  • (Android only) All files in "/data/misc/keychain/certs-added" // User trusted CA folder

Limitations: Unlike the Go language, only the first existing file or directory with at least one file is used. That means Android will never see the user trusted CA folder.

Exceptions

Sourceexception DownloadFailed of string

DownloadFailed msg is the exception raised when the download did not succeed with the error message msg.

Sourceexception DownloadNoncatchableSecurityViolation of string

DownloadNoncatchableSecurityViolation is raised when there is a checksum violation or detection of an insecure channel.

Types

Sourcetype progressphase =
  1. | DownloadInitializing
  2. | Downloading of {
    1. current_bytes : int64;
    2. total_bytes : int64;
    }
  3. | VerifyChecksum of {
    1. current_bytes : int64;
    2. total_bytes : int64;
    }

The phase of progress during a download. The phases are typically conventional. However, the DownloadInitializing and Downloading phase may be executed repeatedly if the download involves redirects.

Sourcetype progressfunction = progressphase -> [ `Continue | `Cancel ]

The type of function that can monitor progress.

The function may return `Continue to continue the download or `Cancel to cancel the download. The return result is advisory and may be ignored.

Functions

Sourceval download_url : ?progress:progressfunction -> ?connect_timeout_ms:int -> ?max_time_ms:int -> ?max_retries:int -> ?allow_insecure_http:unit -> ?downloading_log_prefix:string -> checksum:[ `SHA_256 of string | `SHA3_256 of string ] -> destination:Tr1Fpath_Std.Fpath.t -> Tr1Uri_Std.Uri.t -> unit Lwt.t

download_url ?progress ?connect_timeout_ms ?max_time_ms ?max_retries ?allow_insecure_http ?downloading_log_prefix ~checksum ~destination uri downloads the content at the "https" uri uri expected to have the checksum checksum to the destination file destination in a new lightweight thread.

The ~checksum can be either `SHA_256 hex_encoded_sha256 (most common) or `SHA3_256 hex_encoded_sha3_256.

Set ~progress if you would like notification when progress occurs during the download.

Set ~connect_timeout_ms to the maximum time to connect in milliseconds. The default is unlimited. The connection timer is reset only if a HTTP 302 Redirection is followed.

Set ~max_time_ms to the maximum time allowed to spend downloading. The default is unlimited. When this timeout elapses, the download stops without any errors no matter what is going on at that moment ... including if it is transferring data ... so the failure will only be visible in the checksum validation. The max overall timer is reset only if a HTTP 302 Redirection is followed.

Confer Using curl: timeouts for more details on timeouts.

Set ~max_retries to the maximum number of retries for transient errors. The default is 3. Setting the number to 0 does no retries. Transient error means either: a timeout, an FTP 4xx response code or an HTTP 408, 429, 500, 502, 503 or 504 response code or an HTTP/2 framing error.

Set the ~allow_insecure_http:() flag if you support downloading over an unencrypted, unverified HTTP web site.

Set ~downloading_log_prefix if you want the start of each log DEBUG message to be different than "Downloading ". A trailing space or some other visual separator is recommended.

If the content does not have the hex-encoded SHA-256 checksum uri_sha256 then the download will fail with DownloadNoncatchableSecurityViolation inside the new lightweight thread.

Sourceval fetch_url : ?progress:progressfunction -> ?connect_timeout_ms:int -> ?max_time_ms:int -> ?max_retries:int -> ?allow_insecure_http:unit -> ?fetching_log_prefix:string -> max_sz:int -> Curl_o.Open__.Uri.t -> string Lwt.t

fetch_url ?progress ?connect_timeout_ms ?max_time_ms ?max_retries ?allow_insecure_http ?fetching_log_prefix ~max_sz uri fetch the content at the "https" uri uri having maximum byte size max_sz into memory in a new lightweight thread.

Set ~progress if you would like notification when progress occurs during the download.

Set ~connect_timeout_ms to the maximum time to connect in milliseconds. The default is unlimited. The connection timer is reset only if a HTTP 302 Redirection is followed.

Set ~max_time_ms to the maximum time allowed to spend downloading. The default is unlimited. When this timeout elapses, the download stops without any errors no matter what is going on at that moment ... including if it is transferring data ... so the failure will only be visible in the checksum validation. The max overall timer is reset only if a HTTP 302 Redirection is followed.

Confer Using curl: timeouts for more details on timeouts.

Set ~max_retries to the maximum number of retries for transient errors. The default is 3. Setting the number to 0 does no retries. Transient error means either: a timeout, an FTP 4xx response code or an HTTP 408, 429, 500, 502, 503 or 504 response code or an HTTP/2 framing error.

Set the ~allow_insecure_http:() flag if you support downloading over an unencrypted, unverified HTTP web site.

Set ~fetching_log_prefix if you want the start of each log DEBUG message to be different than "Fetching ". A trailing space or some other visual separator is recommended.

include DkCoder_Std.SCRIPT
Sourceval __init : DkCoder_Std.Context.t -> unit

__init context is the entry point for running a script module. The DkCoder compiler will inject this function at the top and bottom of the script module. The top __init does nothing, while the bottom __init calls the prior __init.

That means:

  1. calling the __init function guarantees that the script module is initialized; that is, all of the script module's side-effects (ex. let () = Format.printf "Hello world@.") are executed before the __init returns to the caller.
  2. you can override the __init function by simply defining the __init idempotently. That will shadow the top __init and when the bottom __init is executed your __init will be called instead of the do-nothing top __init.

Future versions of DkCoder will call __init in dependency order for all `You script modules. Your __init function may be called several times.

Sourceval __repl : DkCoder_Std.Context.t -> unit

__repl context is the entry point for debugging a script module in a REPL. The DkCoder compiler will inject this function at the top and bottom of the script module. The top __repl does nothing, while the bottom __repl calls the prior __repl.

That means:

  1. you can override the __repl function by simply defining the __repl idempotently. That will shadow the top __repl and when the bottom __repl is executed your __repl will be called instead of the do-nothing top __repl.
Sourceval __module_info : unit -> DkCoder_Std.ModuleInfo.t

The run-time module information for the script module.