kbrw · Krapaince · Nov 28, 2025 · Dec 2, 2025 · Nov 28, 2025 · Nov 28, 2025
diff --git a/.formatter.exs b/.formatter.exs
@@ -0,0 +1,52 @@
+locals_without_parens = [
+  resource: 4,
+  resource: 3,
+  defh: 2,
+  pass: 2,
+
+  # Handlers
+  allowed_methods: 1,
+  allow_missing_post: 1,
+  base_uri: 1,
+  charsets_provided: 1,
+  content_types_accepted: 1,
+  content_types_provided: 1,
+  create_path: 1,
+  delete_completed: 1,
+  delete_resource: 1,
+  encodings_provided: 1,
+  expires: 1,
+  forbidden: 1,
+  generate_etag: 1,
+  is_authorized: 1,
+  is_conflict: 1,
+  known_content_type: 1,
+  known_methods: 1,
+  language_available: 1,
+  last_modified: 1,
+  malformed_request: 1,
+  moved_permanently: 1,
+  moved_temporarily: 1,
+  multiple_choices: 1,
+  options: 1,
+  ping: 1,
+  post_is_create: 1,
+  previously_existed: 1,
+  process_post: 1,
+  resource_exists: 1,
+  service_available: 1,
+  uri_too_long: 1,
+  validate_content_checksum: 1,
+  valid_content_headers: 1,
+  valid_entity_length: 1,
+  variances: 1
+]
+
+[
+  import_deps: [
+    :plug
+  ],
+  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"],
+  locals_without_parens: locals_without_parens ++ [decision: 2],
+  export: [locals_without_parens: locals_without_parens]
+]
diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs
@@ -0,0 +1 @@
+ad87df770d2be55ab1becbc05de5d9edf961bad2
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,37 @@
 # Changelog
 
+## Unreleased
+
+## [2.4.0] (2025-12-08)
+
+### Added
+
+- documentation for the handler given to the handlers `content_types_provided`
+  and `content_types_accepted`
+
+### Changed
+
+- Project documentation was rewrote
+- `Ewebmachine.Plug.Debug`, `Ewebmachine.Plug.ErrorAsException`,
+  `Ewebmachine.Plug.ErrorAsForward`, `Ewebmachine.Plug.Run`, and
+  `Ewebmachine.Plug.Send` now implement the `Plug` behaviour. Nothing changed in
+  their implementation.
+- `Ewebmachine.Builder.Resources.resource_quote/4` is now a private function
+- Default `Ewebmachine.Handlers.to_html/2` handler now respond with an empty
+  string instead of with `"<html><body><h1>Hello World</h1></body></html>"`
+
+### Removed
+
+- Publicly exposed function and macro intended for testing purposes:
+    - `Ewebmachine.Handlers.ping/2` (function)
+    - `Ewebmachine.Builder.Handlers.ping/1` (macro)
+- Ewebmachine no longer depends on `plug_cowboy`
+
+### Fixed
+
+- Crash when creating an exception `Ewebmachine.Plug.ErrorAsException` with a
+  `resp_body` which isn't a `bitstring`.
+
 ## [2.3.3] (2025-09-22)
 
 ### Changed

diff --git a/README.md b/README.md
@@ -1,129 +1,159 @@
 # Ewebmachine [![Build Status](https://github.com/kbrw/ewebmachine/actions/workflows/.github/workflows/build-and-test.yml/badge.svg)](https://github.com/kbrw/ewebmachine/actions/workflows/build-and-test.yml) [![Hex.pm](https://img.shields.io/hexpm/v/ewebmachine.svg)](https://hex.pm/packages/ewebmachine) [![Documentation](https://img.shields.io/badge/documentation-gray)](https://hexdocs.pm/ewebmachine) ![Hex.pm License](https://img.shields.io/hexpm/l/ewebmachine)
 
 Ewebmachine is a full rewrite with clean DSL and plug integration
-based on Webmachine from basho. This version is not backward compatible with
-the previous one that was only a thin wrapper around webmachine, use the branch
-1.0-legacy to use the old one.
-
-The principle is to go through the [HTTP decision tree](./assets/http_diagram.png)
-and make decisions according to response of some callbacks called "handlers".
-
-To do that, the library gives you 5 plugs and 2 plug pipeline builders :
-
-- `Ewebmachine.Plug.Run` go through the HTTP decision tree and fill
-  the `conn` response according to it
-- `Ewebmachine.Plug.Send` is used to send a conn set with `Ewebmachine.Plug.Run`
-- `Ewebmachine.Plug.Debug` gives you a debugging web UI to see the
-  HTTP decision path taken by each request.
-- `Ewebmachine.Plug.ErrorAsException` take a conn with a response set but not
-  send, and throw an exception is the status code is an exception
-- `Ewebmachine.Plug.ErrorAsForward` take a conn with a response set but not
-  send, and forward it changing the request to `GET /error/pattern/:status`
-- `Ewebmachine.Builder.Handlers` gives you helpers macros and a
-  `:add_handler` plug to add `handlers` as defined  in
-  `Ewebmachine.Handlers` to your conn, and set the initial user state.
-- `Ewebmachine.Builder.Resources` gives you a `resource` macro to
-  define at the same time an `Ewebmachine.Builder.Handlers` and the
-  matching spec to use it, and a plug `:resource_match` to do the
-  match and execute the associated plug. The macro `resources_plugs` helps you
-  to define common plug pipeline
-
-## Example usage
+based on [Webmachine from basho](https://github.com/webmachine/webmachine). 
+
+[Documentation for Ewebmachine is available on
+hexdocs](https://hexdocs.pm/ewebmachine/readme.html).
+
+## Installation
 
 ```elixir
-defmodule MyJSONApi do 
-  use Ewebmachine.Builder.Handlers
-  plug :cors
-  plug :add_handlers, init: %{}
+    def deps do
+      [
+        {:ewebmachine, "~> 2.3"}
+      ]
+    end
+```
 
-  content_types_provided do: ["application/json": :to_json]
-  defh to_json, do: Poison.encode!(state[:json_obj])
+> [!WARNING]
+> This version is not backward compatible with the previous one that was only a
+> thin wrapper around webmachine, use the branch 1.0-legacy to use the old one.
 
-  defp cors(conn,_), do: 
-    put_resp_header(conn,"Access-Control-Allow-Origin","*")
-end
+## Overview
 
+Ewebmachine is an application layer that adds HTTP semantic awareness on top of
+the excellent `Plug` library. Ewebmachine's DSL provides an easy way to work
+with your application's data.
 
-defmodule ErrorRoutes do
-  use Ewebmachine.Builder.Resources ; resources_plugs
-  resource "/error/:status" do %{s: elem(Integer.parse(status),0)} after 
-    content_types_provided do: ['text/html': :to_html, 'application/json': :to_json]
-    defh to_html, do: "<h1> Error ! : '#{Ewebmachine.Core.Utils.http_label(state.s)}'</h1>"
-    defh to_json, do: ~s/{"error": #{state.s}, "label": "#{Ewebmachine.Core.Utils.http_label(state.s)}"}/
-    finish_request do: {:halt,state.s}
-  end
-end
+## Core concepts
+
+Ewebmachine comes with a few core concepts:
+* **Resource** (a.k.a. any information that can be named): is declared via the
+  `Ewebmachine.Builder.Resources.resource/2` macro which expands into a plug
+  module inside of which handlers are declared.
 
-defmodule FullApi do
+* **Handler**: an handler is a function which return value is used by the
+  decision tree. Each handler has its own purpose and helps you make the
+  appropriate response.
+
+* **(HTTP) Decision tree**: process an HTTP connection by routing it through the
+  decision tree where decisions are taken based on a resource's handlers. Its
+  processing flow is described on [this schema](./assets/http_diagram.png)[^1].
+
+With the core concepts in mind let's go through a simple example:
+```elixir
+defmodule App.Api do
   use Ewebmachine.Builder.Resources
-  if Mix.env == :dev, do: plug Ewebmachine.Plug.Debug
-  resources_plugs error_forwarding: "/error/:status", nomatch_404: true
-  plug ErrorRoutes
 
-  resource "/hello/:name" do %{name: name} after 
-    content_types_provided do: ['application/xml': :to_xml]
-    defh to_xml, do: "<Person><name>#{state.name}</name></Person>"
-  end
+  plug :resource_match
+  plug Ewebmachine.Plug.Run
+  plug Ewebmachine.Plug.Send
+
+  resource "/api/users/:id" do
+    %{user_id: id}
+  after
+    plug App.Api.CommonHandlers
 
-  resource "/hello/json/:name" do %{name: name} after 
-    plug MyJSONApi #this is also a plug pipeline
-    allowed_methods do: ["GET","DELETE"]
-    delete_resource do: DB.delete(state.name)
+    allowed_methods do: ["GET"]
 
-    defh resource_exists do
-      user = DB.get(state.name)
-      pass(user !== nil, json_obj: user)
+    resource_exists do
+      case App.User.fetch(state.user_id) do
+        {:ok, user} -> pass(true, json_obj: user)
+        {:error, :not_found} -> false
+      end
     end
+
+    defh to_json, do: JSON.encode!(state.user)
   end
 
-  resource "/static/*path" do %{path: Enum.join(path,"/")} after
-    resource_exists do:
-      File.regular?(path state.path)
-    content_types_provided do:
-      [{state.path|>Plug.MIME.path|>default_plain,:to_content}]
-    defh to_content, do:
-      File.stream!(path(state.path),[],300_000_000)
-    defp path(relative), do: "#{:code.priv_dir :ewebmachine_example}/web/#{relative}"
-    defp default_plain("application/octet-stream"), do: "text/plain"
-    defp default_plain(type), do: type
+  resource "/api/orders/:id" do
+    %{order_id: id}
+  after
+    plug App.Api.CommonHandlers
+
+    allowed_methods do: ["GET"]
+
+    resource_exists do
+      case App.Order.fetch(state.order_id) do
+        {:ok, order} -> pass(true, json_obj: order)
+        {:error, :not_found} -> false
+      end
+    end
   end
 end
+
+defmodule App.Api.CommonHandlers do
+  use Ewebmachine.Builder.Handlers
+
+  plug :add_handlers, init: %{}
+
+  content_types_provided do: ["application/json": :to_json]
+
+  defh to_json, do: JSON.encode!(state.json_obj)
+end
 ```
 
-## Debug UI 
+Let's go through this example by calling the `App.Api` plug module with a fake
+connection:
+```elixir
+conn = Plug.Test.conn("GET", "/api/users/1")
+conn = App.Api.call(conn, [])
+```
 
-Go to `/wm_debug` to see precedent requests and debug there HTTP
-decision path. The debug UI can be updated automatically on the
-requests.
+The `App.Api` module is a `Plug.Router` composed of the routes `/api/users/:id`
+and `/api/orders/:id` which are defined via the `resource` macro. When our
+connection enter this plug pipeline it first goes through the `:resource_match`
+plug which calls the plugs `:match` and `:dispatch` defined by `Plug.Router`.
+The `/api/users/:id` path being matched, the connection is dispatched to this
+`resource`.
 
-![Debug UI example](./assets/debug_ui.png)
+*The resource macro underneath makes a plug module into which the
+`:add_handlers` plug is added*.
+
+The connection goes through the resource's plug module which contains the
+`App.Api.CommonHandlers` and `:add_handlers` plug.
 
-## Use Cowboy to serve the plug
+*The `:add_handlers` function plug sets inside the connection the module
+implementing each handler. In this example the `allowed_methods` and
+`resource_exists` handlers will be those of the resource module whereas the
+module used for the definition of the `content_types_provided` handler will be
+`App.Api.CommonHandlers`.*
 
-Create a simple supervision tree with only the Cowboy server adapter spec.
+The connection continues through the plug pipeline and then enters the
+`Ewebmachine.Plug.Run` plug which executes the decision tree with the set
+handlers. The response is then sent by the `Ewebmachine.Plug.Send` plug.
 
+## Serve the plug
+
+Ewebmachine exposes plugs therefore it can be served as any other. As referenced
+by [`Plug` itself](https://hexdocs.pm/plug/readme.html#installation) there is
+two options either `plug_cowboy` or `bandit`.
+
+For instance to serve the previous `App.Api` plug with the `plug_cowboy`:
 ```elixir
-defmodule MyApp do
+defmodule App do
   use Application
-  def start(_type, _args), do:
-    Supervisor.start_link([
-        Plug.Cowboy.child_spec(:http,FullApi,[], port: 4000)
-      ], strategy: :one_for_one)
-end
-```
 
-And add it as your application entry point in your `mix.exs`
+  def start(_type, _args) do
+    children = [Plug.Cowboy.child_spec(:http, App.Api, [], port: 80)]
 
-```elixir
-def application do
-  [applications: [:logger,:ewebmachine,:cowboy], mod: {MyApp,[]}]
+    Supervisor.start_link(children, strategy: :one_for_one)
+  end
 end
-defp deps, do:
-  [{:ewebmachine, "2.3.2"}, {:cowboy, "~> 1.0"}]
 ```
 
+## Debug UI 
+
+By adding the `Ewebmachine.Plug.Debug` plug to the plug pipeline of your
+application you can have access to a debug UI exposed on the `/wm_debug` route.
+
+![Debug UI example](./assets/debug_ui.png)
+
 # CONTRIBUTING
 
 Hi, and thank you for wanting to contribute.
 Please refer to the centralized informations available at: https://github.com/kbrw#contributing
 
+[^1]: All credits for this schema goes to Alan Dean and Justin Sheehy. See
+    [here](https://github.com/webmachine/webmachine/wiki/Diagram).
diff --git a/examples/hello/.gitignore b/examples/hello/.gitignore
diff --git a/examples/hello/README.md b/examples/hello/README.md