HTTP server module

OpenSEFA.HTTPServerModule — Module

HTTP server that provides REST API endpoints for data reconciliation problems.

Features

  • RESTful API for solving material flow analysis and substance flow analysis problems.
  • Health endpoint for monitoring server status and performance.
  • Cross-origin resource sharing (CORS) support.
  • Request tracking and statistics.

Endpoints

  • POST /solve: Solves a data reconciliation problem:

    • Accepts JSON payload with content field.
    • Returns solution with objective value, variable values, and residual.
  • GET /health: Returns server health information:

    • Uptime in seconds.
    • Request statistics (total, average time, max time).

Usage

using OpenSEFA

# Start the server on default host (0.0.0.0) and port (8080)
start_server()

# The server can be configured via environment variables:
# - SEFA_SOLVER_HTTP_HOST: Host to bind to
# - SEFA_SOLVER_HTTP_PORT: Port to listen on

Example Client Usage

# Check server health
curl http://localhost:8080/health

# Solve a model from content
curl -X POST http://localhost:8080/solve \
  -H "Content-Type: application/json" \
  -d '{"content": { ... model JSON ... }}'

(see the README.md for a complete minimal example).

source
OpenSEFA.HTTPServerModule.delete — Method
delete(func::Function, path::String)
delete(func::Function, path::HOFRouter)

Convenience function to register a DELETE route. Equivalent to @delete.

source
OpenSEFA.HTTPServerModule.dynamicfiles — Function
dynamicfiles(folder::String, mountdir::String; headers::Vector{Pair{String,String}}=[], loadfile::Union{Function,Nothing}=nothing)

Mount all files inside the /static folder (or user defined mount point), but files are re-read on each request. The headers array will get applied to all mounted files

source
OpenSEFA.HTTPServerModule.get — Method
get(func::Function, path::String)
get(func::Function, path::HOFRouter)

Convenience function to register a GET route. Equivalent to @get.

source
OpenSEFA.HTTPServerModule.internalrequest — Function
internalrequest(req::HTTP.Request; middleware::Vector=[], serialize::Bool=true, catch_errors::Bool=true)

Directly call one of our other endpoints registered with the router, using your own middleware and bypassing any globally defined middleware

source
OpenSEFA.HTTPServerModule.internalrequest — Method
internalrequest(req::Oxygen.Request; middleware::Vector=[], metrics::Bool=false, serialize::Bool=true, catch_errors=true)

Sends an internal request to the server, allowing for communication between different parts of the application.

source
OpenSEFA.HTTPServerModule.patch — Method
patch(func::Function, path::String)
patch(func::Function, path::HOFRouter)

Convenience function to register a PATCH route. Equivalent to @patch.

source
OpenSEFA.HTTPServerModule.post — Method
post(func::Function, path::String)
post(func::Function, path::HOFRouter)

Convenience function to register a POST route. Equivalent to @post.

source
OpenSEFA.HTTPServerModule.put — Method
put(func::Function, path::String)
put(func::Function, path::HOFRouter)

Convenience function to register a PUT route. Equivalent to @put.

source
OpenSEFA.HTTPServerModule.router — Function
router(prefix::String = ""; 
            tags::Vector{String} = Vector{String}(), 
            middleware::Nullable{Vector} = nothing, 
            interval::Nullable{Real} = nothing,
            cron::Nullable{String} = nothing)

Create a new router instance.

Arguments

  • prefix::String: A string to be prefixed to all routes in this router.
  • tags::Vector{String}: A vector of strings to tag the router for documentation and management purposes.
  • middleware::Nullable{Vector}: Optional middleware to be applied to all routes in the router.
  • interval::Nullable{Real}: Optional interval for scheduling tasks.
  • cron::Nullable{String}: Optional cron expression for scheduling tasks.

Returns

A router instance that can be used to define and manage a set of related routes.

source
OpenSEFA.HTTPServerModule.serve — Function
serve(; middleware::Vector=[], handler=stream_handler, host="127.0.0.1", port=8080, async=false, parallel=false, serialize=true, catch_errors=true, docs=true, metrics=true, show_errors=true, show_banner=true, docs_path="/docs", schema_path="/schema", external_url=nothing, access_log=oxygen_logfmt, revise, kwargs...)

Start the webserver with your own custom request handler

source
OpenSEFA.HTTPServerModule.serveparallel — Method
serveparallel(; middleware::Vector=[], handler=stream_handler, host="127.0.0.1", port=8080, serialize=true, async=false, catch_errors=true, docs=true, metrics=true, kwargs...)
source
OpenSEFA.HTTPServerModule.staticfiles — Function
staticfiles(folder::String, mountdir::String; headers::Vector{Pair{String,String}}=[], loadfile::Union{Function,Nothing}=nothing)

Mount all files inside the /static folder (or user defined mount point). The headers array will get applied to all mounted files

source
OpenSEFA.HTTPServerModule.stream — Method
stream(func::Function, path::String)
stream(func::Function, path::HOFRouter)

Convenience function to register a STREAM route. Equivalent to @stream.

source
OpenSEFA.HTTPServerModule.websocket — Method
websocket(func::Function, path::String)
websocket(func::Function, path::HOFRouter)

Convenience function to register a WEBSOCKET route. Equivalent to @websocket.

source
OpenSEFA.HTTPServerModule.@cron — Macro
@cron(expression::String, name::String, func::Function)

This variation provides way manually "name" a registered function. This information is used by the server on startup to log out all cron jobs.

source
OpenSEFA.HTTPServerModule.@cron — Macro
@cron(expression::String, func::Function)

Registers a function with a cron expression. This will extract either the function name or the random Id julia assigns to each lambda function.

source
OpenSEFA.HTTPServerModule.@dynamicfiles — Macro
@dynamicfiles(folder::String, mountdir::String, headers::Vector{Pair{String,String}}=[])

Mount all files inside the /static folder (or user defined mount point), but files are re-read on each request

source
OpenSEFA.HTTPServerModule.@repeat — Macro

@repeat(interval::Real, name::String, func::Function)

This variation provides way manually "name" a registered repeat task. This information is used by the server on startup to log out all cron jobs.

source
OpenSEFA.HTTPServerModule.@repeat — Macro
@repeat(interval::Real, func::Function)

Registers a repeat task. This will extract either the function name or the random Id julia assigns to each lambda function.

source
OpenSEFA.HTTPServerModule.@route — Macro
@route(methods::Array{String}, path::String, func::Function)

Used to register a function to a specific endpoint to handle mulitiple request types

source