olive 🫒

Objectives

Olive is a development tool to help working on a wisp server (AKA the main server in this doc). Olive is a proxy to your main server, that adds the following features:

• Hot reload of any modified erlang modules in your main server
• Live reload of connected browsers to the olive proxy

The different pieces are:

• A proxy to connect to instead of directly to the main server
• Said proxy injects a live reload javascript snippet and handles a websocket connection to trigger connected browsers
• Olive listens for file changes in your source code and:
  1. Triggers a new build when code changes (gleam build)
  2. Hot reload the modified erlang modules of your main server (erlang code:atomic_load/1)
  3. Sends a websocket message to connected browsers so they can reload

Anything else sent to the proxy is directly rerouted to your main server.

Who is this for?

• :x: If you are using lustre, checkout lustre dev tools instead!
• :x: If you are developping an API server, you might be better off with a simple watchexec
• :white_check_mark: If you are working on a server that renders HTML (vanilla, htmx or others), this might interest you!

Caveats / Current limitations

For now, the tool is very much a Proof of Concept. As such, the current limitations are:

• The proxy is on port 1234
• The proxy reroutes to port 3000 (so it forces your main server to listen to 3000)
• Olive must run in the root dir where gleam.toml is so it can get the name of the project to run it.
• Olive speaks (logs) and there is no way to make it quiet for now
• Olive only watches for changes under src/ and nothing else
• All of the above is not configurable but might be in the future!

Because of the nature of the code:atomic_load, any changes to your main function will not be taken into account. Basically, the gleam file ran by the default gleam run, which should be a wisp server, will never be replaced because it is always running. The BEAM never has a chance to swap for the new module. In this case, you have to kill olive and rerun it.

Installation and usage

Add olive has a dev dependency of your main server:

gleam add --dev olive@1

Then, use gleam to run it:

gleam run -m olive

Example

This is a stripped example to show the relevant parts only. Be sure to check the docs for wisp / mist / any other lib that allows to have a server running on the BEAM.

Let's say you did a gleam new my_project.

In src/my_project.gleam:

pub fn main() {
  wisp.configure_logger()

  let assert Ok(_) =
    wisp_mist.handler(router.handle_request, "secret_key")
    |> mist.new
    |> mist.port(3000)
    |> mist.start_http

  process.sleep_forever()
}

In src/my_project/router.gleam:

pub fn handle_request(_req: Request) -> Response {
  response.new(200)
  |> response.set_body(mist.Bytes(bytes_tree.from_string("Hello world")))
}

Now, after installing olive, you can run gleam run -m olive, and the following will happen:

1. Your server will be listening on localhost:3000
2. The olive server will be listening on localhost:1234

Open localhost:1234, and you should be granted with a Hello world.

Now update the file in router.gleam so the server sends back Hello olive, and voila! Your browser should refresh automatically after a quick rebuild and show you the new message :)

Any updates to src/my_project.gleam will not work, as explained in the Caveats chapter.