Tweak APIs, mainly argument order

docs/web/postprocess/index.ml

@@ -694,13 +694,15 @@ let next_replacement = {|
 |}
 
 let write_bigstring_expected = {|<div class="spec value" id="val-write_bigstring">
- <a href="#val-write_bigstring" class="anchor"></a><code><span><span class="keyword">val</span> write_bigstring : <span><a href="#type-bigstring">bigstring</a> <span class="arrow">-&gt;</span></span> <span>int <span class="arrow">-&gt;</span></span> <span>int <span class="arrow">-&gt;</span></span> <span><a href="#type-response">response</a> <span class="arrow">-&gt;</span></span> <span>unit <a href="#type-promise">promise</a></span></span></code>
+ <a href="#val-write_bigstring" class="anchor"></a><code><span><span class="keyword">val</span> write_bigstring : <span>?offset:int <span class="arrow">-&gt;</span></span> <span>?length:int <span class="arrow">-&gt;</span></span> <span><a href="#type-response">response</a> <span class="arrow">-&gt;</span></span> <span><a href="#type-bigstring">bigstring</a> <span class="arrow">-&gt;</span></span> <span>unit <a href="#type-promise">promise</a></span></span></code>
 </div>
 |}
 
 let write_bigstring_replacement = {|
 <pre><span class="keyword">val</span> write_bigstring :
-  <a href="#type-bigstring">bigstring</a> -> int -> int -> <a href="#type-response">response</a> -> unit <a href="#type-promise">promise</a>
+  ?offset:int ->
+  ?length:int ->
+    <a href="#type-response">response</a> -> <a href="#type-bigstring">bigstring</a> -> unit <a href="#type-promise">promise</a>
 </pre>
 |}
 
@@ -891,13 +893,13 @@ let csrf_result_replacement = {|
 |}
 
 let verify_csrf_token_expected = {|<div class="spec value" id="val-verify_csrf_token">
- <a href="#val-verify_csrf_token" class="anchor"></a><code><span><span class="keyword">val</span> verify_csrf_token : <span>string <span class="arrow">-&gt;</span></span> <span><a href="#type-request">request</a> <span class="arrow">-&gt;</span></span> <span><a href="#type-csrf_result">csrf_result</a> <a href="#type-promise">promise</a></span></span></code>
+ <a href="#val-verify_csrf_token" class="anchor"></a><code><span><span class="keyword">val</span> verify_csrf_token : <span><a href="#type-request">request</a> <span class="arrow">-&gt;</span></span> <span>string <span class="arrow">-&gt;</span></span> <span><a href="#type-csrf_result">csrf_result</a> <a href="#type-promise">promise</a></span></span></code>
 </div>
 |}
 
 let verify_csrf_token_replacement = {|
 <pre><span class="keyword">val</span> verify_csrf_token :
-  string -> <a href="#type-request">request</a> -> <a href="#type-csrf_result">csrf_result</a> <a href="#type-promise">promise</a>
+  <a href="#type-request">request</a> -> string -> <a href="#type-csrf_result">csrf_result</a> <a href="#type-promise">promise</a>
 </pre>
 |}
 
@@ -1033,14 +1035,14 @@ let websocket_replacement = {|
 |}
 
 let send_expected = {|<div class="spec value" id="val-send">
- <a href="#val-send" class="anchor"></a><code><span><span class="keyword">val</span> send : <span>?kind:<span>[ `Text <span>| `Binary</span> ]</span> <span class="arrow">-&gt;</span></span> <span>string <span class="arrow">-&gt;</span></span> <span><a href="#type-websocket">websocket</a> <span class="arrow">-&gt;</span></span> <span>unit <a href="#type-promise">promise</a></span></span></code>
+ <a href="#val-send" class="anchor"></a><code><span><span class="keyword">val</span> send : <span>?kind:<span>[ `Text <span>| `Binary</span> ]</span> <span class="arrow">-&gt;</span></span> <span><a href="#type-websocket">websocket</a> <span class="arrow">-&gt;</span></span> <span>string <span class="arrow">-&gt;</span></span> <span>unit <a href="#type-promise">promise</a></span></span></code>
 </div>
 |}
 
 let send_replacement = {|
 <pre><span class="keyword">val</span> send :
   ?kind:[ `Text | `Binary ] ->
-    string -> <a href="#type-websocket">websocket</a> -> unit <a href="#type-promise">promise</a>
+    <a href="#type-websocket">websocket</a> -> string -> unit <a href="#type-promise">promise</a>
 </pre>
 |}
 
@@ -1069,13 +1071,13 @@ let graphql_replacement = {|
 |}
 
 let sql_expected = {|<div class="spec value" id="val-sql">
- <a href="#val-sql" class="anchor"></a><code><span><span class="keyword">val</span> sql : <span><span>(<span><span class="xref-unresolved">Caqti_lwt</span>.connection <span class="arrow">-&gt;</span></span> <span><span class="type-var">'a</span> <a href="#type-promise">promise</a></span>)</span> <span class="arrow">-&gt;</span></span> <span><a href="#type-request">request</a> <span class="arrow">-&gt;</span></span> <span><span class="type-var">'a</span> <a href="#type-promise">promise</a></span></span></code>
+ <a href="#val-sql" class="anchor"></a><code><span><span class="keyword">val</span> sql : <span><a href="#type-request">request</a> <span class="arrow">-&gt;</span></span> <span><span>(<span><span class="xref-unresolved">Caqti_lwt</span>.connection <span class="arrow">-&gt;</span></span> <span><span class="type-var">'a</span> <a href="#type-promise">promise</a></span>)</span> <span class="arrow">-&gt;</span></span> <span><span class="type-var">'a</span> <a href="#type-promise">promise</a></span></span></code>
 </div>
 |}
 
 let sql_replacement = {|
 <pre><span class="keyword">val</span> sql :
-  (Caqti_lwt.connection -> 'a <a href="#type-promise">promise</a>) -> <a href="#type-request">request</a> ->
+  <a href="#type-request">request</a> -> (Caqti_lwt.connection -> 'a <a href="#type-promise">promise</a>) ->
     'a <a href="#type-promise">promise</a>
 </pre>
 |}

example/h-sql/README.md

@@ -27,12 +27,7 @@ let add_comment =
   fun text (module Db : DB) ->
     let%lwt unit_or_error = Db.exec query text in
     Caqti_lwt.or_fail unit_or_error
-```
-
-...then, a template for our CSRF-safe form, like in example
-[**`d-form`**](../d-form#files):
 
-```ocaml
 let render comments request =
   <html>
     <body>
@@ -46,11 +41,7 @@ let render comments request =
 
     </body>
   </html>
-```
-
-...and finally, the Web app itself, which connects to `db.sqlite`:
 
-```ocaml
 let () =
   Dream.run
   @@ Dream.logger
@@ -59,13 +50,13 @@ let () =
   @@ Dream.router [
 
     Dream.get "/" (fun request ->
-      let%lwt comments = Dream.sql list_comments request in
+      let%lwt comments = Dream.sql request list_comments in
       Dream.html (render comments request));
 
     Dream.post "/" (fun request ->
       match%lwt Dream.form request with
       | `Ok ["text", text] ->
-        let%lwt () = Dream.sql (add_comment text) request in
+        let%lwt () = Dream.sql request (add_comment text) in
         Dream.redirect request "/"
       | _ ->
         Dream.empty `Bad_Request);

example/h-sql/sql.eml.ml

@@ -40,13 +40,13 @@ let () =
   @@ Dream.router [
 
     Dream.get "/" (fun request ->
-      let%lwt comments = Dream.sql list_comments request in
+      let%lwt comments = Dream.sql request list_comments in
       Dream.html (render comments request));
 
     Dream.post "/" (fun request ->
       match%lwt Dream.form request with
       | `Ok ["text", text] ->
-        let%lwt () = Dream.sql (add_comment text) request in
+        let%lwt () = Dream.sql request (add_comment text) in
         Dream.redirect request "/"
       | _ ->
         Dream.empty `Bad_Request);

example/j-stream/README.md

@@ -13,7 +13,7 @@ let echo request response =
     | None ->
       Dream.close_stream response
     | Some chunk ->
-      let%lwt () = Dream.write chunk response in
+      let%lwt () = Dream.write response chunk in
       let%lwt () = Dream.flush response in
       loop ()
   in

example/j-stream/stream.ml

@@ -4,7 +4,7 @@ let echo request response =
     | None ->
       Dream.close_stream response
     | Some chunk ->
-      let%lwt () = Dream.write chunk response in
+      let%lwt () = Dream.write response chunk in
       let%lwt () = Dream.flush response in
       loop ()
   in

example/k-websocket/README.md

@@ -41,7 +41,7 @@ let () =
         Dream.websocket (fun websocket ->
           match%lwt Dream.receive websocket with
           | Some "Hello?" ->
-            let%lwt () = Dream.send "Good-bye!" websocket in
+            let%lwt () = Dream.send websocket "Good-bye!" in
             Dream.close_websocket websocket
           | _ ->
             Dream.close_websocket websocket));

example/k-websocket/websocket.eml.ml

@@ -31,7 +31,7 @@ let () =
         Dream.websocket (fun websocket ->
           match%lwt Dream.receive websocket with
           | Some "Hello?" ->
-            let%lwt () = Dream.send "Good-bye!" websocket in
+            let%lwt () = Dream.send websocket "Good-bye!" in
             Dream.close_websocket websocket
           | _ ->
             Dream.close_websocket websocket));

example/w-server-sent-events/server_sent_events.eml.ml

@@ -58,7 +58,7 @@ let rec forward_messages response =
   |> List.map (Printf.sprintf "data: %s\n\n")
   |> String.concat ""
   |> fun text ->
-    let%lwt () = Dream.write text response in
+    let%lwt () = Dream.write response text in
     let%lwt () = Dream.flush response in
     forward_messages response
 

example/w-stress-response/stress_response.ml

@@ -19,8 +19,8 @@ let stress ?(megabytes = 1024) ?(chunk = 64) response =
       let%lwt () = Dream.close_stream response in
       Lwt.return (Unix.gettimeofday () -. start)
     else
-      let%lwt () = Dream.write chunk_a response in
-      let%lwt () = Dream.write chunk_b response in
+      let%lwt () = Dream.write response chunk_a in
+      let%lwt () = Dream.write response chunk_b in
       let%lwt () = Lwt.pause () in
       loop (sent + chunk + chunk)
   in

example/w-stress-websocket-send/stress_websocket_send.eml.ml

@@ -39,8 +39,8 @@ let stress websocket =
       let%lwt () = Dream.close_websocket websocket in
       Lwt.return (Unix.gettimeofday () -. start)
     else
-      let%lwt () = Dream.send frame_a websocket ~kind:`Binary in
-      let%lwt () = Dream.send frame_b websocket ~kind:`Binary in
+      let%lwt () = Dream.send websocket frame_a ~kind:`Binary in
+      let%lwt () = Dream.send websocket frame_b ~kind:`Binary in
       let%lwt () = Lwt.pause () in
       loop (sent + frame + frame)
   in

example/z-playground/server/playground.ml

@@ -149,12 +149,12 @@ let forward ?(add_newline = false) sandbox message =
   in
   `Assoc ["kind", `String "log"; "payload", `String message]
   |> Yojson.Basic.to_string
-  |> fun message -> Dream.send message sandbox.socket
+  |> fun message -> Dream.send sandbox.socket message
 
 let started sandbox port =
   `Assoc ["kind", `String "started"; "payload", `Int port]
   |> Yojson.Basic.to_string
-  |> fun message -> Dream.send message sandbox.socket
+  |> fun message -> Dream.send sandbox.socket message
 
 let run sandbox id =
   let%lwt port = allocate_port () in
@@ -219,7 +219,7 @@ let rec communicate sandbox =
           let%lwt () =
             `Assoc ["kind", `String "content"; "payload", `String content]
             |> Yojson.Basic.to_string
-            |> fun s -> Dream.send s sandbox.socket
+            |> fun s -> Dream.send sandbox.socket s
           in
           communicate sandbox
 

src/dream.mli

@@ -470,7 +470,7 @@ val stream :
     {[
       fun request ->
         Dream.stream (fun response ->
-          let%lwt () = Dream.write "foo" response in
+          let%lwt () = Dream.write response "foo" in
           Dream.close_stream response)
     ]} *)
 
@@ -671,7 +671,7 @@ val with_stream : response -> response
     {!Dream.write} will be accepted before then. See {!Dream.stream} for a more
     convenient wrapper. *)
 
-val write : string -> response -> unit promise
+val write : response -> string -> unit promise
 (** Streams out the string. The promise is fulfilled when the response can
     accept more writes. *)
 
@@ -710,8 +710,10 @@ val next :
     - [~close] if close is requested, and
     - [~exn] to report an exception. *)
 
-val write_bigstring : bigstring -> int -> int -> response -> unit promise
-(** Streams out the {!bigstring} slice. *)
+val write_bigstring :
+  ?offset:int -> ?length:int -> response -> bigstring -> unit promise
+(** Streams out the {!bigstring} slice. [~offset] defaults to zero. [~length]
+    defaults to the length of the {!bigstring}, minus [~offset]. *)
 
 
 
@@ -965,8 +967,8 @@ val csrf_token : ?valid_for:float -> request -> string
     seconds. The default value is one hour ([3600.]). Dream uses signed tokens
     that are not stored server-side. *)
 
-val verify_csrf_token : string -> request -> csrf_result promise
-(** Checks that the CSRF token is valid for the request's session. *)
+val verify_csrf_token : request -> string -> csrf_result promise
+(** Checks that the CSRF token is valid for the {!type-request}'s session. *)
 
 
 
@@ -1352,11 +1354,11 @@ val websocket :
     {[
       let my_handler = fun request ->
         Dream.websocket (fun websocket ->
-          let%lwt () = Dream.send "Hello, world!" websocket in
+          let%lwt () = Dream.send websocket "Hello, world!" in
           Dream.close_websocket websocket);
     ]} *)
 
-val send : ?kind:[ `Text | `Binary ] -> string -> websocket -> unit promise
+val send : ?kind:[ `Text | `Binary ] -> websocket -> string -> unit promise
 (** Sends a single message. The WebSocket is ready another message when the
     promise resolves.
 
@@ -1481,7 +1483,7 @@ val graphiql : string -> handler
 val sql_pool : ?size:int -> string -> middleware
 (** Makes an SQL connection pool available to its inner handler. *)
 
-val sql : (Caqti_lwt.connection -> 'a promise) -> request -> 'a promise
+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}
     [h-sql]}.
@@ -1491,7 +1493,7 @@ val sql : (Caqti_lwt.connection -> 'a promise) -> request -> 'a promise
         Dream.run
         @@ Dream.sql_pool "sqlite3://db.sqlite"
         @@ fun request ->
-          request |> Dream.sql (fun db ->
+          Dream.sql request (fun db ->
             (* ... *) |> Dream.html)
     ]} *)
 

src/eml/eml.ml

@@ -686,7 +686,7 @@ struct
     print;
 
     init = (fun () ->
-      print "let ___eml_write string = Dream.write string response in\n");
+      print "let ___eml_write string = Dream.write response string in\n");
 
     finish = (fun () ->
       print "Lwt.return_unit\n");
@@ -705,7 +705,7 @@ struct
     print;
 
     init = (fun () ->
-      print "let ___eml_write = string => Dream.write(string, response);\n");
+      print "let ___eml_write = string => Dream.write(response, string);\n");
 
     finish = (fun () ->
       print "Lwt.return_unit\n");

src/graphql/graphql.ml

@@ -145,7 +145,7 @@ let handle_over_websocket make_context schema subscriptions request websocket =
         close_and_clean subscriptions websocket ~code:4429
       end
       else begin
-        let%lwt () = Dream.send ack_message websocket in
+        let%lwt () = Dream.send websocket ack_message in
         loop true
       end
 
@@ -193,13 +193,13 @@ let handle_over_websocket make_context schema subscriptions request websocket =
               log.warning (fun log ->
                 log ~request
                   "subscribe: error %s" (Yojson.Basic.to_string json));
-              Dream.send (error_message id json) websocket
+              Dream.send websocket (error_message id json)
 
             (* It's not clear that this case ever occurs, because graphql-ws is
                only used for subscriptions, at the protocol level. *)
             | Ok (`Response json) ->
-              let%lwt () = Dream.send (data_message id json) websocket in
-              let%lwt () = Dream.send (complete_message id) websocket in
+              let%lwt () = Dream.send websocket (data_message id json) in
+              let%lwt () = Dream.send websocket (complete_message id) in
               Lwt.return_unit
 
             | Ok (`Stream (stream, close)) ->
@@ -216,15 +216,15 @@ let handle_over_websocket make_context schema subscriptions request websocket =
               let%lwt () =
                 stream |> Lwt_stream.iter_s (function
                   | Ok json ->
-                    Dream.send (data_message id json) websocket
+                    Dream.send websocket (data_message id json)
                   | Error json ->
                     log.warning (fun log ->
                       log ~request
                         "Subscription: error %s" (Yojson.Basic.to_string json));
-                    Dream.send (error_message id json) websocket)
+                    Dream.send websocket (error_message id json))
               in
 
-              let%lwt () = Dream.send (complete_message id) websocket in
+              let%lwt () = Dream.send websocket (complete_message id) in
               Hashtbl.remove subscriptions id;
               Lwt.return_unit
 
@@ -240,11 +240,11 @@ let handle_over_websocket make_context schema subscriptions request websocket =
             try%lwt
               let%lwt () =
                 Dream.send
-                  (error_message id (make_error "Internal Server Error"))
                   websocket
+                  (error_message id (make_error "Internal Server Error"))
               in
               if !subscribed then
-                Dream.send (complete_message id) websocket
+                Dream.send websocket (complete_message id)
               else
                 Lwt.return_unit
             with _ ->

src/middleware/csrf.ml

@@ -34,7 +34,7 @@ type csrf_result = [
   | `Invalid
 ]
 
-let verify_csrf_token token request = Lwt.return @@
+let verify_csrf_token request token = Lwt.return @@
   match Dream__pure.Formats.from_base64url token with
   | None ->
     log.warning (fun log -> log ~request "CSRF token not Base64-encoded");

src/middleware/form.ml

@@ -32,7 +32,7 @@ let sort_and_check_form to_value form request =
 
   match csrf_token with
   | [_, value] ->
-    begin match%lwt Csrf.verify_csrf_token (to_value value) request with
+    begin match%lwt Csrf.verify_csrf_token request (to_value value) with
     | `Ok ->
       Lwt.return (`Ok form)