Road to v1

[cmcaine]

This is an issue to collect ideas on what needs to be done to get this package to v1.

Here are some of my ideas:

• add docstrings and a small manual we need more examples #28
• document what is in the stable API and what is not (is stuff in src/examples covered by stability guarantee?)
  • At the moment, we expect both Mux and users to make changes to the request and response dicts and don't provide any guidance about what keys are reserved for Mux and which the user can freely use.
• support HTTPS added https #25
• more test coverage
  • we don't test examples/files.jl (the only security-relevant code ;)
  • or that @app allows hot reloading
• make wait(serve(app)) respond to SIGINT better
  • I can't kill a server started with julia myserver.jl with ctrl-c
  • Providing serve_sync is probably best.
• make sure do syntax works in the places we would expect it to
  • e.g. both page(app, path) and page(path, app) are defined, so we can use it there, though it's a little bit weird that we have both
• provide the original HTTP.Request in the req dict?
• allow apps to return an HTTP.Response somehow?
  • Why? Let response return a HTTP.Response object #152
• nicer stacktraces Make stacktraces more readable #87
  • in the common case that @app gets a tuple, we could make the macro save the identity and names of each somewhere and the error catcher could re-write the stacktrace with that info?
• maybe some more routing options/branches? (Scheme based routing (WIP) #38, GSoC 2017: Middlewares for common web application chores in Mux.jl #41, How do I match the whole path? #54)
  • It's pretty easy to do yourself, but there are a few issues looking for helper functions something like these:
    • e.g. branch(req -> predicate(req[:uri]), app)
    • e.g. branch(req -> predicate(req[:cookies]), app)
    • e.g. branch(req -> predicate(req[:headers]), app)
    • e.g. branch(req -> req[:uri].scheme == scheme, app)
  • Maybe we can just document this better.
• check performance? (Performance metrics? #92)
  • mux should be viable for small, low-latency queries too, if possible
  • multiprocessing or multithreading support
  • it would be sad if you find you need better performance and it turns out Mux has some show-stoppers that mean you have to re-write in another framework.
• Decide if relative paths should be relative to the script file, or the working directory, or disallowed allow "." directory path to specify the root of files #26
  • current behaviour is that relative paths are accepted but only allow access to the root directory listing and not any of its content, which is not useful.
  • we can do it with root = isabspath(root) ? root : normpath(@__DIR__, root)
  • Here be security dragons if root is provided by the user, but there's no particular reason to let it be (check AssetRegistry integration).
• return an IO body from fresp? HTTP.Response now supports this, we'd just need to return Dict(:body => open(f))
• decide if files() should URL decode the given path by default support assetserving of files with spaces #105
• Drop pkgfiles and assetserver out of Mux.defaults?

Please add your ideas, too!

Related: #41 (GSoC 2017 ideas)

[cmcaine]

v1 was released without discussion, so any breaking changes can now be in Mux 2.0, I guess.