Communication between the client and the server

Besides values passed by the mean of the %variable syntax, there are multiple ways for the client and server to exchange values.

Client requesting data

The client process can call special services to get some OCaml values. They are registered using Eliom_registration.​Ocaml and can be called using Eliom_client.​call_caml_service.

Those services cannot be visited by the browser as web pages. You usually want POST coservices for this use. This corresponds to remote function calls, that are typically handled by non-attached POST coservices.

Example of use:

open Eliom_content

let pi_service =
  Eliom_registration.Ocaml.register_post_coservice'
    ~post_params:Eliom_parameter.unit
    (fun () () -> Lwt.return 3.1415926535)

let _ =
  My_appl.register_service
    ~path:["pi"]
    ~get_params:Eliom_parameter.unit
    (fun () () ->
      ignore {unit{
        Lwt.ignore.result(
          lwt pi =
            Eliom_client.call_caml_service ~service:%pi_service () ()
          in
	  Lwt.return (
	    Dom_html.window##alert(Js.string
                ("pi = "^(string_of_float pi)))))
      }};
      Lwt.return
        Html5.D.(html
                  (head (title (pcdata "pi")) [])
                  (body [])))

Since client and server side value representation are not the same, it is not possible to send any Ocaml value, the restriction on what can be sent are the same as for the %variable mechanism (see the chapter Wrapping).

Client sending data

The client can send OCaml values as parameters to services. To do that, declare the expected parameter type using Eliom_parameter.​caml.

Since the server can't trust the client to send correcly formed data, Eliom is not using the standard OCaml marshalling mechanism (the server needs to be able to check that the value is of the expected type). For this reason, you must declare the types of the data you want to be able to send to the server using the Deriving syntax extension:

{shared{
  type some_type = (int * string list) deriving (Json)
  type another_type =
    | A of some_type
    | B of another_type
    deriving (Json)
}}

This type can now be used as a parameter for a service:

open Eliom_content

let s =
  My_appl.register_service
    ~path:["s1"]
    ~get_params:(caml "param" Json.t<another_type>)
    (fun () v ->
      Lwt.return
        Html5.D.(html
                  (head (title (pcdata "title")))
                  (body [
                    match v with
                      | A _ -> pcdata "A"
                      | B _ -> pcdata "B"
                  ])))

let _ =
  My_appl.register_service
    ~path:["s2"]
    ~get_params:unit
    (fun () () ->
      Lwt.return
        Html5.D.(html
                  (head (title (pcdata "title")))
                  (body [
                    [p ~a:[a_onclick
                      {{ ignore (Eliom_client.change_page ~service:%s (A (1,["s"])) ()) }}]
                      [pcdata "Click to send Ocaml data"]
                  ]])))

It works for the data types you define, and the data types from OCaml's standard library. For types defined in third third party libraries, have a look at deriving's documentation and Js_of_ocaml's Deriving_Json.

Server sending data

Eliom implements some mechanisms to make possible for the server to send data to a client. We call that mechanism Comet, it is also sometimes called HTTP push.

The simple low level version above which all other following mechanisms are implemented is provided in the Eliom_comet.​Channels module.

Comet defines channels which can convey data. A channel is created using a Lwt stream. It is a kind of cooperative lazy list.

The two main methods to create a stream are through the functions Lwt_stream.​from and Lwt_stream.​create.

val from : (unit -> 'a option Lwt.t) -> 'a t
val create : unit -> 'a t * ('a option -> unit)

Function Lwt_stream.​from makes possible to create a stream where a new value is added each time a function returns. Function Lwt_stream.​create returns a stream and a function to push new values to the stream.

On client side the type Eliom_comet.​Channels.​t is just a Lwt stream Lwt_stream.​t.

There are 3 kind of channels depending on how you want to send data.

  • Channels created with Eliom_comet.​Channels.​create have a buffer with a limited size. Message are read from the stream as soon as they are available, i.e. for stream created with Lwt_stream.​from, that means that the function is called another time as soon as the previous one terminate. For stream created with Lwt_stream.​create, this is as soon as they are pushed. If the client missed too much messages (more than the size of the buffer) it will receive an exception Eliom_comet.​Channel_full when reading data from the stream.

Channels can be closed on client side by cancelling a thread waiting for data on it.

Like services, channels have a scope (only site or client process). The constraints vary with respect to the scope you choose:

  • Channels created with scope Eliom_common.​default_process_scope must be created inside a service handler. They are assigned to a particular client process. Different channels created with the same stream do not share memory. They are closed when requested or when the client process is closed. It is possible to know when a client stop requesting data on those channels using Eliom_comet.​Channels.​wait_timeout.

Warning: Be careful about memory consumption when using client process channels.

Comet configuration

The server can push data to a client only when the client has an open HTTP connection waiting for answer. As of now, a comet request can only last at most 10 seconds. After that, the client can either do a new request or stale for some time: this is the activity behaviour. This can be configured on client side, using the functions from Eliom_comet.​Configuration

For instance if you receive data which doesn't need frequent update, you could set the time between different requests quite high and stop requesting data as soon as the browser looses the focus.

open Eliom_comet.Configuration
let slow_c = new_configuration () in
set_active_until_timeout slow_c false;
set_time_between_request slow_c 60.

If you need more reactivity for a few seconds, do:

open Eliom_comet.Configuration
let fast_c = new_configuration () in
set_set_always_active fast_c true;
set_set_time_between_request fast_c 0.;
ignore (Lwt_js.sleep 10. >|= (fun () -> drop_configuration fast_c))

The original setting will be reset after the drop.

Reactive values

A common usage of comet is for the server to update a value available on client side. A convenient way to implement this is to use reactive programming. Eliom provides a reactive interface for channels, using Daniel Bünzli's React library.

To share a React event or signal with the client, use functions Eliom_react.​Down.​of_react or Eliom_react.​S.​Down.​of_react

On client side the value returned by those functions is directly a React event or signal.

The contrary is also available using Eliom_react.​Up.​create.

Since this is implemented using comet, tunnig comet configuration will also affect the behaviour of shared react variables.

Client-Server shared bus

It is cometimes useful to have a bidirectionnal channels shared between multiple clients. This is the purpose of buses. Those are created using Eliom_bus.​create. Since the server will also receive data on the bus, the description of the type (using deriving) is needed to create a bus.

Like comet channels, the behaviour of buses can be tuned using the module Eliom_comet.​Configuration. There are additionnal configurations available on buses to tune the client side buffering.

Another Server sending data (Comet on another server)

It is possible to access a named stateless channel created on another server. It has to be declared using Eliom_comet.​Channels.​external_channel. The declaration of the channel must match exactly the creation. The server generating the page and the server that created the channel must run exactly the same version of Eliom. By default a browser can't do requests to a different server, to allow that the server serving the channel must allow Cross-Origin Resource Sharing using the CORS Ocsigenserver extension.

Remote Procedure Call

Eliom provides you an easy way to call server functions from the client: Eliom_pervasives.​server_function (and on client).

A function 'a -> 'b Lwt.t can me wrapped on the server side by Eliom_pervasives.​server_function. When the result is sent to the client, it appears as a plain function 'a -> 'b Lwt.

It is necessary to provide an instance of Deriving_Json for the argument type, to safely send the argument from the client to the server.

Every call to server_function creates a new non-attached POST coservice. It is thus advisable to apply it only once and bind it to an identifier, if it is to be used several times.

Example:

{server{
  let log str =
    Lwt_io.write_line Lwt_io.stdout str
  let rpc_log =
    server_function Json.t<string> log
}}

{client{
  let () =
    Eliom_client.onload
      (* NB The service underlying the server_function isn't available on the
         client before loading the page. *)
      (fun () ->
         Lwt.async
           (fun () ->
              %rpc_log "hello from the client to the server!"))
}}

Exceptions raised in the server-side function cannot be handled directly on the client (because it's impossible to marshal them in OCaml to send it to the client). Instead, if an exception is raised in the server function, the function application fails (in Lwt) on the client with the exception Eliom_lib.​Exception_on_server whose argument describes the original exception (according to Printexc.to_string).