Sinatra-inspired web routing DSL, includes streaming. Interested in feedback

Chat / Discussions
,
1

I have started experimenting with a web routing Domain Specific Language(DSL).

The DSL is inspired from working with several minimal web frameworks including Sinatra, roda etc. The heritage is not overly important as the question is about macro best practice. I wanted a simple DSL but my particular requirement was to match on url before method.

My first attempt looked like the following.

route "/user/:id" do
  :GET ->
    IO.inspect(id) # This implicit variable matches the identifier from the URL
    IO.inspect(request) # This implicit variable is always added to the context
    IO.inspect(config) # Same as request
    # actual work here to return request
  :POST ->
    # Other methods etc
end

However to create this DSL I have needed to use Macro.var, and this can mess with the hygiene of a macro. To see what would be required to not implicitly set variables I got to the following DSL.

route "/users/:id", [user_id] do
  get(request, config) ->
    IO.inspect(user_id) # explicitly named in route macro
    IO.inspect(request) # explicitly named in get macro
    IO.inspect(config) # Same as request
    # actual work here to return request
  post(r) ->
    IO.inspect(r) # Named r for brevity
    # config not used so not matched on
end

I see the trade off between the two as follows, version one is slightly more succinct but at the cost of being more “magic”. In addition this magic messing with the hygiene of the macro may have further side effects that I don’t know about yet.

Because of this I am leaning towards favoring the second more explicit DSL but would be interested in other opinions.

Update:

I have abandoned efforts to write a Sinatra style routing DSL. As any useful API must be documented I have decided to use that documentation as a router. My implementation of this is Raxx.Blueprint that will parse an API Blueprint file and generate forward requests to controllers based on that.

4 Likes
2

I subscribe to the Python credo of “Explicit is better than Implicit”. ^.^

4 Likes
3

It’s a simple guide however certainly gives an answer I wouldn’t argue with.

1 Like
4

Here is what an example chat server currently looks like, with this DSL

defmodule Example do
  use Tokumei

  config :port, 8080
  config :static, "./public"
  config :templates, "./templates"

  route "/" do
    get() ->
      ok(home_page())
    post(%{body: body}) ->
      {:ok, %{message: message}} = PublishForm.parse(body)
      {:ok, _} = ChatRoom.publish(message)
      redirect("/")
  end

  route "/updates" do
    get() ->
      {:ok, _} = ChatRoom.join()
      SSE.stream(:updates)
  end

  SSE.streaming :updates do
    {:message, message} ->
      {:send, %{event: "chat", data: "message"}
    _ ->
      {:nosend}
  end
end

Hopefully it the majority of the example is self explanatory.I hope to push the first version to hex soon

5 Likes
5

There is now a first release of this router. The Tokumei framework has a super alpha first release and a generator to get you started

mix archive.install https://github.com/crowdhailer/tokumei/raw/master/tokumei_new.ez
mix tokumei.new my_app
cd my_app
iex -S mix

A more thorough example, which includes streaming server sent event, is included in the source repo. It’s a chatroom naturally.

3 Likes
6

Working on an update that will route to specific modules, rather than writing actions inline. This will be helpful in writing larger applications. I am looking for opinions on possibilities for the routing sytanx.

required features are

  • fixed matching
  • variable matching
  • wildcard matching
  • subpath mounting
  • named routes for helpers

Option 1
as above, i.e. path first.
advantages are not having to repeat path declaration and being able to automatically return 405 response

@name :posts
route "/posts",
  GET: ShowPostsPage,
  POST: CreatePost

@name :post
route "/posts/:id",
  GET: ShowPostPage,
  PUT: UpdatePost

@name :search
route "/search/*blob",
  GET: SearchPage

mount "/api", APIController

Option 2
method first
advantages are similar to plug/sinatra/rails

@name :posts
get "/posts", ShowPostsPage,
post "/posts", CreatePost

@name :post
get "/posts/:id", ShowPostPage
put "/posts/:id", UpdatePost

@name :search
get "/search/*blob", SearchPage

mount "/api", APIControlle
1 Like
7

I’d think Option 2 would be best so you could potentially match to out of order get/post’s like is common in Plug/Phoenix.

8

Sorry, I don’t know what you mean by this:

9

The streaming solution above was unsatisfactory. keeping track of streaming state from several possible endpoints in a single module was challenging.

A better idea is to use a module for each endpoint each of those having several callbacks for the state of the stream. This PR expands on the idea. https://github.com/CrowdHailer/raxx/pull/47

1 Like
10

I can report that experiments on a streaming interface have now finished.
The most flexible approach was to use multiple callbacks for various stages in the streaming process.

Here is an example of a client streaming data to a server.

defmodule StreamingRequest do
  use Raxx.Server

  def handle_headers(%Raxx.Request{method: :PUT, body: true}, _config) do
    {:ok, io_device} = File.open("my/path")
    {[], {:file, device}}
  end

  def handle_fragment(fragment, state = {:file, device}) do
    IO.write(device, fragment)
    {[], state}
  end

  def handle_trailers(_trailers, state) do
    Raxx.response(:see_other)
    |> Raxx.set_header("location", "/")
  end
end

Here is an example of a server streaming data to the client.

defmodule SubscribeToMessages do
  use Raxx.Server

  def handle_headers(_request, _config) do
    {:ok, _} = ChatRoom.join()
    Raxx.response(:ok)
    |> Raxx.set_header("content-type", "text/plain")
    |> Raxx.set_body(true)
  end

  def handle_info({ChatRoom, data}, config) do
    {[Raxx.fragment(data)], config}
  end
end

For full details see the Raxx.Server documentation
I hope to share a few example usecases in the next few weeks.

1 Like
11

ace_http 0.5.0 released with HTTP/1.1 support for streaming.

This release of :ace_http implements the Raxx Streaming interface described above (latest interface docs

1 Like
12

Final comment to close of this thread.

I have abandoned efforts to write a Sinatra style routing DSL. As any useful API must be documented I have decided to use that documentation as a router. My implementation of this is Raxx.Blueprint that will parse an API Blueprint file and generate forward requests to controllers based on that.

4 Likes