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
contentfield. - Returns solution with objective value, variable values, and residual.
- Accepts JSON payload with
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 onExample 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).
OpenSEFA.HTTPServerModule.Model — Type
Struct holding either the model's content.
OpenSEFA.HTTPServerModule.CorsMiddleware — Method
CORS Middleware to handle preflight requests and add CORS headers.
OpenSEFA.HTTPServerModule.adjustparams — Method
adjustparams(path, func)Adjust the order of path and func based on their types. This is used to support the do ... end syntax for the routing macros.
OpenSEFA.HTTPServerModule.clearcronjobs — Function
Clears all cron job defintions
OpenSEFA.HTTPServerModule.clearcronjobs — Method
clearcronjobs(ctx::ServerContext)
clearcronjobs()Clear all registered cron jobs.
OpenSEFA.HTTPServerModule.cleartasks — Function
cleartasks(ct::ServerContext)Clear any stored repeat task definitions
OpenSEFA.HTTPServerModule.cleartasks — Method
cleartasks(context::ServerContext)
cleartasks()Clear all registered repeat tasks.
OpenSEFA.HTTPServerModule.delete — Method
delete(func::Function, path::String)
delete(func::Function, path::HOFRouter)Convenience function to register a DELETE route. Equivalent to @delete.
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
OpenSEFA.HTTPServerModule.get — Method
get(func::Function, path::String)
get(func::Function, path::HOFRouter)Convenience function to register a GET route. Equivalent to @get.
OpenSEFA.HTTPServerModule.getexternalurl — Method
getexternalurl()Return the external URL of the service
OpenSEFA.HTTPServerModule.getschema — Method
getschema()Return the current internal schema for this app
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
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.
OpenSEFA.HTTPServerModule.patch — Method
patch(func::Function, path::String)
patch(func::Function, path::HOFRouter)Convenience function to register a PATCH route. Equivalent to @patch.
OpenSEFA.HTTPServerModule.post — Method
post(func::Function, path::String)
post(func::Function, path::HOFRouter)Convenience function to register a POST route. Equivalent to @post.
OpenSEFA.HTTPServerModule.put — Method
put(func::Function, path::String)
put(func::Function, path::HOFRouter)Convenience function to register a PUT route. Equivalent to @put.
OpenSEFA.HTTPServerModule.resetstate — Method
resetstate()Reset all the internal state variables
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.
OpenSEFA.HTTPServerModule.router — Function
No documentation found.
Binding Oxygen.Core.AutoDoc.router does not exist.
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
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...)OpenSEFA.HTTPServerModule.setschema — Method
setschema(customschema::Dict)Overwrites the entire internal schema
OpenSEFA.HTTPServerModule.start_server — Method
Start the web server with CORS middleware applied.
OpenSEFA.HTTPServerModule.startcronjobs — Function
startcronjobs()Start all the cron cronjobs within their own async task. Each individual task will loop conintually and sleep untill the next time it's suppost to
OpenSEFA.HTTPServerModule.startcronjobs — Method
startcronjobs(ctx::ServerContext)
startcronjobs()Start all registered cron jobs.
OpenSEFA.HTTPServerModule.starttasks — Function
starttasks()Start all background repeat tasks
OpenSEFA.HTTPServerModule.starttasks — Method
starttasks(context::ServerContext)
starttasks()Start all registered repeat tasks.
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
OpenSEFA.HTTPServerModule.stop_server — Method
Stop the web server.
OpenSEFA.HTTPServerModule.stopcronjobs — Function
stopcronjobs()Stop each background task by toggling a global reference that all cron jobs reference
OpenSEFA.HTTPServerModule.stopcronjobs — Method
stopcronjobs(ctx::ServerContext)
stopcronjobs()Stop all running cron jobs.
OpenSEFA.HTTPServerModule.stoptasks — Function
stoptasks()Stop all background repeat tasks
OpenSEFA.HTTPServerModule.stoptasks — Method
stoptasks(context::ServerContext)
stoptasks()Stop all running repeat tasks.
OpenSEFA.HTTPServerModule.stream — Method
stream(func::Function, path::String)
stream(func::Function, path::HOFRouter)Convenience function to register a STREAM route. Equivalent to @stream.
OpenSEFA.HTTPServerModule.terminate — Function
terminate(ctx)Gracefully shuts down the webserver
OpenSEFA.HTTPServerModule.terminate — Method
terminate(context::ServerContext)
terminate()Terminate the server and stop all running tasks.
OpenSEFA.HTTPServerModule.track_request_time — Method
Track request processing time.
OpenSEFA.HTTPServerModule.websocket — Method
websocket(func::Function, path::String)
websocket(func::Function, path::HOFRouter)Convenience function to register a WEBSOCKET route. Equivalent to @websocket.
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.
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.
OpenSEFA.HTTPServerModule.@delete — Macro
@delete(path::String, func::Function)Used to register a function to a specific endpoint to handle DELETE requests
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
OpenSEFA.HTTPServerModule.@get — Macro
@get(path::String, func::Function)Used to register a function to a specific endpoint to handle GET requests
OpenSEFA.HTTPServerModule.@patch — Macro
@patch(path::String, func::Function)Used to register a function to a specific endpoint to handle PATCH requests
OpenSEFA.HTTPServerModule.@post — Macro
@post(path::String, func::Function)Used to register a function to a specific endpoint to handle POST requests
OpenSEFA.HTTPServerModule.@put — Macro
@put(path::String, func::Function)Used to register a function to a specific endpoint to handle PUT requests
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.
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.
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
OpenSEFA.HTTPServerModule.@staticfiles — Macro
@staticfiles(folder::String, mountdir::String, headers::Vector{Pair{String,String}}=[])Mount all files inside the /static folder (or user defined mount point)
OpenSEFA.HTTPServerModule.@stream — Macro
@stream(path::String, func::Function)Used to register a function to a specific endpoint to handle Streaming requests
OpenSEFA.HTTPServerModule.@websocket — Macro
@websocket(path::String, func::Function)Used to register a function to a specific endpoint to handle WebSocket connections