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
I subscribe to the Python credo of “Explicit is better than Implicit”. ^.^
4 Likes
It’s a simple guide however certainly gives an answer I wouldn’t argue with.
1 Like
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
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
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
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.
Sorry, I don’t know what you mean by this:
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
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
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
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