Oxygen.jl Documentation

Handlers connect your code to the server by assigning a URL to a function. When an incoming request matches that URL, the function is invoked.

Key concepts:

• Type-based identification: The type of the first argument determines the handler type. If no type information is provided, Oxygen assumes it is a Request handler by default.
• Syntax options: Handlers support standard function definitions, do..end blocks, arrow functions, and even functions declared in other modules.
• Modularity: Handlers can be imported from other modules to keep your project organized.

Supported handler types:

1. Request Handlers: Handle standard HTTP requests. Use @get, @post, @put, @patch, @delete, or @route macros (or their function equivalents). They accept a HTTP.Request as the first argument.
2. Stream Handlers: Used for streaming data. Use the @stream macro or stream() function. They accept a HTTP.Stream as the first argument. You must explicitly include the type definition so Oxygen can identify them.
3. Websocket Handlers: Handle websocket connections. Use the @websocket macro or websocket() function. They accept a HTTP.WebSocket as the first argument. Note that websocket handshakes typically use the GET protocol, so they can also be assigned with @get or get() if the type is explicitly defined.

using HTTP
using Oxygen

# Request Handler
@get "/" function(req::HTTP.Request)
    ...
end

# Stream Handler
@stream "/stream" function(stream::HTTP.Stream)
    ...
end

# Websocket Handler
@websocket "/ws" function(ws::HTTP.WebSocket)
    ...
end

Oxygen provides built-in extractors to reduce boilerplate when serializing inputs (path parameters, query params, headers, etc.) into structured types. You define a struct and use the corresponding extractor in your handler signature. The deserialized data is accessed via the .payload property.

Supported Extractors:

• Path: Extracts from path parameters.
• Query: Extracts from query parameters.
• Header: Extracts from request headers.
• Form: Extracts form data from the request body.
• Body: Serializes the entire request body to a type (e.g., String, Float64).
• ProtoBuffer: Extracts ProtoBuf messages (requires package extension).
• Json: Extracts JSON from the request body.
• JsonFragment: Extracts a specific top-level key from a JSON body using the parameter name.

struct Add
    b::Int
    c::Int
end

@get "/add/{a}/{b}/{c}" function(req, a::Int, pathparams::Path{Add})
    add = pathparams.payload # access the serialized payload
    return a + add.b + add.c
end

The context is a shared global state (e.g., database pools) available throughout the application lifetime. You can set it when calling serve(context=...).

Note: Oxygen does not provide built-in data race protections for the context. For mutable shared state, use Actors, Channels, or ReentrantLocks.

There are three ways to access the context in a handler:

1. Injection: Use the Context{T} struct in the function signature.
2. Keyword Argument: Use the context keyword argument.
3. Function Call: Use the context() function.

using Oxygen

struct Person
    name::String
end

# 1. Injection
@get "/ctx-injection" function(req, ctx::Context{Person})
    person = ctx.payload
    return "Hello $(person.name)!"
end

# 2. Keyword argument
@get "/ctx-kwarg" function(req; context)
    return "Hello $(context.name)!"
end

# 3. Function call
@get "/ctx-function" function(req)
    return "Hello $(context().name)!"
end

person = Person("John")
serve(context=person)

Oxygen includes a built-in cron scheduling system. You can schedule endpoints via a router or standalone functions using the @cron macro. The parser follows the Spring Cron specification.

Cron Syntax: Six space-separated fields: second minute hour day-of-month month day-of-week.

Capabilities:

• Endpoints: Use the cron keyword in router() to trigger an endpoint automatically.
• Functions: Use @cron "expression" function() ... end to run background tasks that are not exposed via the API.
• Lifecycle: Jobs start automatically when serve() or serveparallel() is called and stop when the server is terminated. Use startcronjobs() and stopcronjobs() for manual control.

# Schedule an endpoint via router
# Executes at 8, 9, and 10 o'clock every day
@get router("/cron-example", cron="0 0 8-10 * * *") function(req)
    println("here")
end

# Schedule a background function
@cron "*/2" function()
    println("runs every 2 seconds")
end

Oxygen supports running multiple web servers within the same module using two approaches:

Static approach with @oxidize

Best if the number of instances is known ahead of time. Use the @oxidize macro in separate modules. Each module acts as an independent instance that can be started via its own .serve() method.

Dynamic approach with instance()

Best for creating completely independent instances at runtime. The instance() function dynamically creates a new Julia module. You can access all Oxygen methods (like .get(), .post(), .serve()) using dot syntax on the returned object.

# Dynamic approach example
using Oxygen

app1 = instance()
app1.get("/") do
    text("server A")
end

app2 = instance()
app2.get("/") do
    text("server B")
end

try 
    app1.serve(port=8001, async=true)
    app2.serve(port=8002)
finally
    app1.terminate()
    app2.terminate()
end