diff --git a/src/dream.mli b/src/dream.mli index 708bba04..4307df6f 100644 --- a/src/dream.mli +++ b/src/dream.mli @@ -21,11 +21,11 @@ and response = server message and handler = request -> response promise (** Handlers are asynchronous functions from requests to responses. Example - {{:https://github.com/aantron/dream/tree/master/example/1-hello#files} + {{:https://github.com/aantron/dream/tree/master/example/1-hello#folders-and-files} [1-hello]} shows the simplest handler, an anonymous function which we pass to {!Dream.run}. This creates a complete Web server! You can also see the Reason version in example - {{:https://github.com/aantron/dream/tree/master/example/r-hello#files} + {{:https://github.com/aantron/dream/tree/master/example/r-hello#folders-and-files} [r-hello]}. {[ @@ -37,7 +37,7 @@ and handler = request -> response promise and middleware = handler -> handler (** Middlewares are functions that take a {!handler}, and run some code before or after — producing a “bigger” handler. Example - {{:https://github.com/aantron/dream/tree/master/example/2-middleware#files} + {{:https://github.com/aantron/dream/tree/master/example/2-middleware#folders-and-files} [2-middleware]} inserts the {!Dream.logger} middleware into a Web app: {[ @@ -48,9 +48,9 @@ and middleware = handler -> handler ]} Examples - {{:https://github.com/aantron/dream/tree/master/example/4-counter#files} + {{:https://github.com/aantron/dream/tree/master/example/4-counter#folders-and-files} [4-counter]} and - {{:https://github.com/aantron/dream/tree/master/example/5-promise#files} + {{:https://github.com/aantron/dream/tree/master/example/5-promise#folders-and-files} [5-promise]} show user-defined middlewares: {[ @@ -72,7 +72,7 @@ and middleware = handler -> handler and route (** Routes tell {!Dream.router} which handler to select for each request. See {!section-routing} and example - {{:https://github.com/aantron/dream/tree/master/example/3-router#files} + {{:https://github.com/aantron/dream/tree/master/example/3-router#folders-and-files} [3-router]}. Routes are created by helpers such as {!Dream.get} and {!Dream.scope}: @@ -122,7 +122,7 @@ and server = Dream_pure.Message.server and 'a promise = 'a Lwt.t (** Dream uses {{:https://github.com/ocsigen/lwt} Lwt} for promises and asynchronous I/O. See example - {{:https://github.com/aantron/dream/tree/master/example/5-promise#files} + {{:https://github.com/aantron/dream/tree/master/example/5-promise#folders-and-files} [5-promise]}. Use [raise] to reject promises. If you are writing a library, you may prefer @@ -402,7 +402,7 @@ val query : request -> string -> string option (** First query parameter with the given name. See {{:https://tools.ietf.org/html/rfc3986#section-3.4} RFC 3986 §3.4} and example - {{:https://github.com/aantron/dream/tree/master/example/w-query#files} + {{:https://github.com/aantron/dream/tree/master/example/w-query#folders-and-files} [w-query]}. *) val queries : request -> string -> string list @@ -449,7 +449,7 @@ val html : As your Web app develops, consider adding [Content-Security-Policy] headers, as described in example - {{:https://github.com/aantron/dream/tree/master/example/w-content-security-policy#files} + {{:https://github.com/aantron/dream/tree/master/example/w-content-security-policy#folders-and-files} [w-content-security-policy]}. These headers are completely optional, but they can provide an extra layer of defense for a mature app. *) @@ -460,7 +460,7 @@ val json : string -> response promise (** Same as {!Dream.respond}, but adds [Content-Type: application/json]. See {!Dream.application_json} and example - {{:https://github.com/aantron/dream/tree/master/example/e-json#files} + {{:https://github.com/aantron/dream/tree/master/example/e-json#folders-and-files} [e-json]}. *) val redirect : @@ -526,7 +526,7 @@ val set_header : 'a message -> string -> string -> unit {!Dream.set_cookie} and {!Dream.cookie} are designed for round-tripping secure cookies. The most secure settings applicable to the current server are inferred automatically. See example - {{:https://github.com/aantron/dream/tree/master/example/c-cookie#files} + {{:https://github.com/aantron/dream/tree/master/example/c-cookie#folders-and-files} [c-cookie]}. {[ @@ -568,7 +568,7 @@ val set_cookie : decrypt cookies from prior starts. See example - {{:https://github.com/aantron/dream/tree/master/example/c-cookie#files} + {{:https://github.com/aantron/dream/tree/master/example/c-cookie#folders-and-files} [c-cookie]}. Most of the optional arguments are for overriding inferred defaults. @@ -655,7 +655,7 @@ val cookie : ?secure:bool -> request -> string -> string option (** First cookie with the given name. See example - {{:https://github.com/aantron/dream/tree/master/example/c-cookie#files} + {{:https://github.com/aantron/dream/tree/master/example/c-cookie#folders-and-files} [c-cookie]}. {[ @@ -676,7 +676,7 @@ val all_cookies : request -> (string * string) list val body : 'a message -> string promise (** Retrieves the entire body. See example - {{:https://github.com/aantron/dream/tree/master/example/6-echo#files} + {{:https://github.com/aantron/dream/tree/master/example/6-echo#folders-and-files} [6-echo]}. *) val set_body : 'a message -> string -> unit @@ -700,7 +700,7 @@ val stream : (stream -> unit promise) -> response promise (** Creates a response with a {!type-stream} open for writing, and passes the stream to the callback when it is ready. See example - {{:https://github.com/aantron/dream/tree/master/example/j-stream#files} + {{:https://github.com/aantron/dream/tree/master/example/j-stream#folders-and-files} [j-stream]}. {[ @@ -714,7 +714,7 @@ val stream : val read : stream -> string option promise (** Retrieves a body chunk. See example - {{:https://github.com/aantron/dream/tree/master/example/j-stream#files} + {{:https://github.com/aantron/dream/tree/master/example/j-stream#folders-and-files} [j-stream]}. *) (* TODO Document difference between receiving a request and receiving on a WebSocket. *) @@ -848,7 +848,7 @@ val websocket : (** Creates a fresh [101 Switching Protocols] response. Once this response is returned to Dream's HTTP layer, the callback is passed a new {!type-websocket}, and the application can begin using it. See example - {{:https://github.com/aantron/dream/tree/master/example/k-websocket#files} + {{:https://github.com/aantron/dream/tree/master/example/k-websocket#folders-and-files} [k-websocket]}. {[ @@ -909,7 +909,7 @@ val close_websocket : ?code:int -> websocket -> unit promise for generating JSON parsers and serializers for OCaml data types. See example - {{:https://github.com/aantron/dream/tree/master/example/e-json#files} + {{:https://github.com/aantron/dream/tree/master/example/e-json#folders-and-files} [e-json]}. *) val origin_referrer_check : middleware @@ -961,7 +961,7 @@ val origin_referrer_check : middleware ]} See example - {{:https://github.com/aantron/dream/tree/master/example/d-form#files} + {{:https://github.com/aantron/dream/tree/master/example/d-form#folders-and-files} [d-form]}. *) type 'a form_result = [ @@ -975,7 +975,7 @@ type 'a form_result = [ ] (** Form CSRF checking results, in order from least to most severe. See {!Dream.val-form} and example - {{:https://github.com/aantron/dream/tree/master/example/d-form#files} + {{:https://github.com/aantron/dream/tree/master/example/d-form#folders-and-files} [d-form]}. The first three constructors, [`Ok], [`Expired], and [`Wrong_session] can @@ -1060,7 +1060,7 @@ type multipart_form = ]} See example - {{:https://github.com/aantron/dream/tree/master/example/g-upload#files} + {{:https://github.com/aantron/dream/tree/master/example/g-upload#folders-and-files} [g-upload]} and {{:https://datatracker.ietf.org/doc/html/rfc7578} RFC 7578}. Note that clients such as curl can send files with no filename ([None]), @@ -1090,7 +1090,7 @@ val multipart : ?csrf:bool -> request -> multipart_form form_result promise ]} See section {!section-templates}, and example - {{:https://github.com/aantron/dream/tree/master/example/g-upload#files} + {{:https://github.com/aantron/dream/tree/master/example/g-upload#folders-and-files} [g-upload]}. Note that, like {!Dream.form}, this function sorts form fields by field @@ -1193,18 +1193,18 @@ let render message = v} See examples - {{:https://github.com/aantron/dream/tree/master/example/7-template#files} + {{:https://github.com/aantron/dream/tree/master/example/7-template#folders-and-files} [7-template]} and - {{:https://github.com/aantron/dream/tree/master/example/r-template#files} + {{:https://github.com/aantron/dream/tree/master/example/r-template#folders-and-files} [r-template]}. There is also a typed alternative, provided by an external library, {{:https://github.com/ocsigen/tyxml} TyXML}. It is shown in example - {{:https://github.com/aantron/dream/tree/master/example/w-tyxml#files} + {{:https://github.com/aantron/dream/tree/master/example/w-tyxml#folders-and-files} [w-tyxml]}. If you are using Reason syntax, TyXML can be used with {{:https://ocsigen.org/tyxml/latest/manual/jsx} server-side JSX}. See example - {{:https://github.com/aantron/dream/tree/master/example/r-tyxml#files} + {{:https://github.com/aantron/dream/tree/master/example/r-tyxml#folders-and-files} [r-tyxml]}. To use the built-in templates, add this to [dune]: @@ -1227,9 +1227,9 @@ let render message = supported presently is [%% response] for streaming the template using {!Dream.write}, to a {!type-response} that is in scope. This is shown in examples - {{:https://github.com/aantron/dream/tree/master/example/w-template-stream#files} + {{:https://github.com/aantron/dream/tree/master/example/w-template-stream#folders-and-files} [w-template-stream]} and - {{:https://github.com/aantron/dream/tree/master/example/r-template-stream#files} + {{:https://github.com/aantron/dream/tree/master/example/r-template-stream#folders-and-files} [r-template-stream]}. A template ends... @@ -1360,7 +1360,7 @@ val router : route list -> handler (** Creates a router. If none of the routes match the request, the router responds with [404 Not Found]. Route components starting with [:] are parameters, which can be retrieved with {!Dream.param}. See example - {{:https://github.com/aantron/dream/tree/master/example/3-router#files} + {{:https://github.com/aantron/dream/tree/master/example/3-router#folders-and-files} [3-router]}. {[ @@ -1481,7 +1481,7 @@ val static : ?loader:(string -> string -> handler) -> string -> handler (** Serves static files from a local directory. See example - {{:https://github.com/aantron/dream/tree/master/example/f-static#files} + {{:https://github.com/aantron/dream/tree/master/example/f-static#folders-and-files} [f-static]}. {[ @@ -1506,7 +1506,7 @@ val static : - [path] is what was substituted for [**]. The default loader is {!Dream.from_filesystem}. See example - {{:https://github.com/aantron/dream/tree/master/example/w-one-binary#files} + {{:https://github.com/aantron/dream/tree/master/example/w-one-binary#folders-and-files} [w-one-binary]} for a loader that serves files from memory instead. *) val from_filesystem : string -> string -> handler @@ -1563,7 +1563,7 @@ val mime_lookup : string -> (string * string) list the next request that it is assigned to. See example - {{:https://github.com/aantron/dream/tree/master/example/b-session#files} + {{:https://github.com/aantron/dream/tree/master/example/b-session#folders-and-files} [b-session]}. *) val session_field : request -> string -> string option @@ -1624,7 +1624,7 @@ val session_expires_at : request -> float Flash messages are short strings which are stored in cookies during one request, to be made available for the next request. The typical use case is to provide form feedback across a redirect. See example - {{:https://github.com/aantron/dream/tree/master/example/w-flash#files} + {{:https://github.com/aantron/dream/tree/master/example/w-flash#folders-and-files} [w-flash]}. *) val flash : middleware @@ -1643,11 +1643,11 @@ val add_flash_message : request -> string -> string -> unit Dream integrates {{:https://github.com/andreas/ocaml-graphql-server#readme} ocaml-graphql-server}. See examples: - - {{:https://github.com/aantron/dream/tree/master/example/i-graphql#files} + - {{:https://github.com/aantron/dream/tree/master/example/i-graphql#folders-and-files} [i-graphql]} - - {{:https://github.com/aantron/dream/tree/master/example/r-graphql#files} + - {{:https://github.com/aantron/dream/tree/master/example/r-graphql#folders-and-files} [r-graphql]} - - {{:https://github.com/aantron/dream/tree/master/example/w-graphql-subscription#files} + - {{:https://github.com/aantron/dream/tree/master/example/w-graphql-subscription#folders-and-files} [w-graphql-subscription]}. If you are also @@ -1719,7 +1719,7 @@ val graphiql : ?default_query:string -> string -> handler Dream provides thin convenience functions over {{:https://github.com/paurkedal/ocaml-caqti/#readme} Caqti}, an SQL interface with several back ends. See example - {{:https://github.com/aantron/dream/tree/master/example/h-sql#files} + {{:https://github.com/aantron/dream/tree/master/example/h-sql#folders-and-files} [h-sql]}. Dream installs the core {{:https://opam.ocaml.org/packages/caqti/} [caqti]} @@ -1754,7 +1754,7 @@ val sql_pool : ?size:int -> string -> middleware val sql : request -> (Caqti_lwt.connection -> 'a promise) -> 'a promise (** Runs the callback with a connection from the SQL pool. See example - {{:https://github.com/aantron/dream/tree/master/example/h-sql#files} + {{:https://github.com/aantron/dream/tree/master/example/h-sql#folders-and-files} [h-sql]}. {[ @@ -1784,7 +1784,7 @@ val sql : request -> (Caqti_lwt.connection -> 'a promise) -> 'a promise val logger : middleware (** Logs and times requests. Time spent logging is included. See example - {{:https://github.com/aantron/dream/tree/master/example/2-middleware#files} + {{:https://github.com/aantron/dream/tree/master/example/2-middleware#folders-and-files} [2-middleware]}. *) val log : ('a, Format.formatter, unit, unit) format4 -> 'a @@ -1793,7 +1793,7 @@ val log : ('a, Format.formatter, unit, unit) format4 -> 'a {{:https://v2.ocaml.org/api/Printf.html#VALfprintf} [Printf]} and {{:https://v2.ocaml.org/api/Format.html#VALfprintf} [Format]}. The rest of the arguments are determined by the format string. See example - {{:https://github.com/aantron/dream/tree/master/example/a-log#files} + {{:https://github.com/aantron/dream/tree/master/example/a-log#folders-and-files} [a-log]}. {[ @@ -1820,7 +1820,7 @@ val error : ('a, unit) conditional_log (** Formats a message and writes it to the log at level [`Error]. The inner formatting function is called only if the {{!initialize_log} current log level} is [`Error] or higher. See example - {{:https://github.com/aantron/dream/tree/master/example/a-log#files} + {{:https://github.com/aantron/dream/tree/master/example/a-log#folders-and-files} [a-log]}. {[ @@ -1865,7 +1865,7 @@ val sub_log : ?level:[< log_level] -> string -> sub_log unless {!Dream.set_log_level} is used. See [README] of example - {{:https://github.com/aantron/dream/tree/master/example/a-log#files} + {{:https://github.com/aantron/dream/tree/master/example/a-log#folders-and-files} [a-log]}. *) val initialize_log : @@ -2043,7 +2043,7 @@ type error_handler = error -> response option promise val error_template : (error -> string -> response -> response promise) -> error_handler (** Builds an {!error_handler} from a template. See example - {{:https://github.com/aantron/dream/tree/master/example/9-error#files} + {{:https://github.com/aantron/dream/tree/master/example/9-error#folders-and-files} [9-error]}. {[ @@ -2127,19 +2127,19 @@ val run : promise that never resolves. - [~error_handler] handles all errors, both from the application, and low-level errors. See {!section-errors} and example - {{:https://github.com/aantron/dream/tree/master/example/9-error#files} + {{:https://github.com/aantron/dream/tree/master/example/9-error#folders-and-files} [9-error]}. {!Dream.debug_error_handler} is a default error handler that can be passed here to help debug Web apps. See example - {{:https://github.com/aantron/dream/tree/master/example/8-debug#files} + {{:https://github.com/aantron/dream/tree/master/example/8-debug#folders-and-files} [8-debug]}. - [~tls:true] enables TLS. You should also specify [~certificate_file] and [~key_file]. However, for development, Dream includes an insecure compiled-in - {{:https://github.com/aantron/dream/tree/master/src/certificate#files} + {{:https://github.com/aantron/dream/tree/master/src/certificate#folders-and-files} localhost certificate}. Enabling HTTPS also enables transparent upgrading of connections to HTTP/2. See example - {{:https://github.com/aantron/dream/tree/master/example/l-https#files} + {{:https://github.com/aantron/dream/tree/master/example/l-https#folders-and-files} [l-https]}. - [~certificate_file] and [~key_file] specify the certificate and key file, respectively, when using [~tls]. They are not required for development,