GitHub

Router

This module provides the route macros @GET, @POST, @PUT, @PATCH, and @DELETE matching their HTTP verbs, along with @STREAM and @WEBSOCKET macros. These are used to define HTTP route handlers within the enclosing module.

Routes must be defined within a submodule, or submodules, of the Julia package that implements your application. For example, a Routes module:

module Routes

using ReloadableMiddleware.Router

Handler functions can be named or unnamed function definitions. Named functions can later be referenced in HTML templates via Validated router paths.

@GET "/" function (req)
    # Anything can be returned from the handler. It will be converted
    # to an `HTTP.Response` automatically. See the `Responses` module
    # for details.
    return "page content..."
end

path parameters

Use the same {} syntax as HTTP. Additionally include a path keyword that declares the type of each path parameter. StructTypes is used for the deserialization of these parameters.

@GET "/page/{id}" function (req; path::@NamedTuple{id::Int})
    @show path.id
    # ...
end

body parameters

Post requests specify their typed body contents as below. This is expected to be urlencoded Content-Type.

@POST "/form" function (req; body::@NamedTuple{a::String,b::Base.UUID})
    @show body.a, body.b
    # ...
end

query parameters

Query parameters are specified using the query keyword. These are urlencoded values, and are deserialized, like the previous examples using StructTypes.

@GET "/search" function (req; query::@NamedTuple{q::String})
    @show query.q
    # ...
end

JSON3.jl integration

JSON data can be deserialized using the JSON type. Anything that the JSON3 package handles can be handled with this type. allow_inf is set to true for deserialization.

@POST "/api/v1/info" function (req; body::JSON{Vector{Float64}})
    @show vec = body.json
    # ...
end

Multipart form data

Multipart form data can be deserialized using the Multipart and RawFile type as below.

@POST "/file-upload" function (req; body::Multipart{@NamedTuple{file::RawFile}})
    @show body.multipart.file body.multipart.data
    # ...
end

Multipart form data can also be deserialized using the Multipart and File type as below. .data will contain a Vector{Int} rather than raw bytes. The Content-Type of the part denotes how it will be deserialized, either as JSON or urlencoded.

@POST "/file-upload-typed" function (
    req;
    body::Multipart{@NamedTuple{file::File{Vector{Int}}}},
)
    @show body.multipart.file body.multipart.data
    # ...
end

Scoped Routes

The @prefix and @middleware macros allow for defining "scoped" routes. This provides a way to group a set of routes under a common path prefix and a scoped set of middleware that should be applied in addition to the Server-level middleware.

These macros work on the module-level, ie. only a single usage per-module is allowed and affects all routes defined within the module. Use different modules to separate different sets of routes, for example a Routes.API module to define a JSON API that lives under a /api/v1 route prefix.

module Routes

@GET "/" function (req)
    # The actual `/` handler.
end

module API

@prefix "/api/v1"

@middleware function (handler)
    function (req)
        # Run custom middleware code here. Only runs for routes under `/api/v1`.
        return handler(req)
    end
end

@GET "/" function (req)
    # Handles `/api/v1`, not `/`.
end

end

end

Validated router paths

You can construct valid paths to any defined route by calling the route handler function with no positional arguments and either/both of the path and query keyword arguments. If called with invalid values it will fail at runtime to construct the path. This only works for named route handler functions.

@GET "/users/{id}" function user_details(req; path::@NamedTuple{id::Int})
    # ...
end

# ...

user_details(; path = (; id = 1)) == "/users/1"
user_details(; path = (; id = "id")) # Throws an error.
ReloadableMiddleware.Router.File — Type
File{T}

Used within a Multipart body annotation to mark the form part as being a file that should be converted into a File object. The T type parameter is used to specify the type of the file contents for deserialization. When using this rather than a RawFile the Content-Type for the file must be either application/json or application/x-www-form-urlencoded to be suitable for deserialization.

source
ReloadableMiddleware.Router.JSON — Type
JSON{T}

Mark a body keyword in a route handler as being JSON data that should be deserialized into type T using the JSON3 package. Within the route handler access the JSON values via body.json. alllow_inf is set to true.

source
ReloadableMiddleware.Router.Multipart — Type
Multipart{T}

Mark a body keyword in a route handler as being multipart/form-data that should be parsed an deserialized using HTTP.parse_multipart_form. Each part of the request body is deserialized using the appropriate deserializer for it's Content-Type, e.g. application/json and application/x-www-form-urlencoded. See the File type for marking a form part as being a file. If a field in a multipart form is a checkbox deserialize it into Union{Bool,Nothing} since if unchecked, it will not be sent as part of the request.

source
ReloadableMiddleware.Router.RawFile — Type

A type alias for File{Vector{UInt8}} useful for when the file contents is unstructured, or you need to deserialize it after first processing the request completely.

source
ReloadableMiddleware.Router.routes — Function
routes(mod::Module | mods::Vector{Module})

Builds an HTTP.Router based on the currently defined route handlers in the given modules. When run in a dev server each time the routes defined within the provided modules change it will rebuild the router between requests such that you do not need to restart the server to see changes reflected.

source
ReloadableMiddleware.Router.@POST — Macro
@POST path function [name](request::HTTP.Request; [path], [query], [body])
    # ...
    return response
end

Register a POST method handler for the given path.

See @route for further details.

source
ReloadableMiddleware.Router.@STREAM — Macro
@STREAM path function [name](stream::HTTP.Stream; [path], [query])
    # ...
    for each in iter
        # ...
        write(stream, data)
    end
end

Register a handler for server sent events for the given path.

Note that updating the handler body with Revise will not update the code of any active connections. You will need to restart those connections first. Alternatively you can break out the for loop body into a separate function that does the bulk of your processing and call it with @invokelatest. Best to not do this for production code though, and keep it only for debugging handlers.

See @route for further details.

source
ReloadableMiddleware.Router.@WEBSOCKET — Macro
@WEBSOCKET path function [name](ws::HTTP.Websocket; [path], [query])
    # ...
    for message in ws
        # ...
        HTTP.send(ws, response)
    end
end

Register a handler for websocket connections for the given path.

Note that updating the handler body with Revise will not update the code of any active connections. You will need to restart those connections first. Alternatively you can break out the for loop body into a separate function that does the bulk of your processing and call it with @invokelatest. Best to not do this for production code though, and keep it only for debugging handlers.

See @route for further details.

source
ReloadableMiddleware.Router.@middleware — Macro
@middleware function (handler)
    function (req)
        # before...
        res = handler(req)
        # after...
        return res
    end
end
@middleware [funcs...]

Run the provided middleware functions for all routes in the module in which this @middleware is defined. This middleware function matches the signature that normal middleware functions for HTTP.jl use. handler -> (req -> res).

A "stack" of middleware functions, with the same signature as above, can be chained by passing an iterable of functions rather than a single function definition.

source
ReloadableMiddleware.Router.@route — Macro
@route METHOD path function [name](request | stream; [path], [query], [body])
    # ...
    return response
end

path must be a valid HTTP.register! path, since that is what is used internally to register routes.

handler is a named (or unnamed) function taking one positional argument, the HTTP.Request, or HTTP.Stream for @STREAM and @WEBSOCKET. Three optional keyword arguments are available for use. They are path, query, and body. They must be type annotated with a concrete type that the request should be deserialized into.

If a named function is provided then a validated path builder is defined for this route that will construct the string representing a valid route that this handler responds to. This builder takes two optional keyword arguments, path, and query. Those are interpolated into the resulting path in the expected locations.

source