[ANN] Oxygen.jl v1.1.6 (Cron Scheduling)

Nathan Ortega — Mon, 10 Apr 2023 00:17:54 +0000

Hello, everyone!

Today, I'm here to introduce the latest update to the Oxygen.jl. It's been almost a year since my last post, and I've been steadily working on incorporating your feedback and implementing new features to enhance the development experience.

In this post, I'll specifically discuss the most recent addition to the framework: Cron Scheduling. This feature allows you to schedule recurring tasks effortlessly for both endpoints and standalone functions, using the same Cron expressions we're all familiar with.

Additionally, I'll briefly cover the most significant updates that have been introduced since last time. The latest version offers a range of improvements designed to help you build more robust and versatile applications.

Updated:

JSON serialization & deserialization (customizable):
- This package has always supported automatic JSON serialization and deserialization for request and response data. But now you can also define your own serializers and deserializers by using middleware functions.

Added:

Cron Scheduling:
- Added support for Cron scheduling, which makes it easy to schedule recurring tasks to run at specific intervals for both endpoints and functions.
Repeat Tasks:
- Added the ability to create tasks that repeat at specified intervals, making it easy to schedule and manage recurring tasks within your application.
Middleware:
- Middleware functions enable the creation of custom workflows to intercept incoming requests and outgoing responses in a specific order. They can be set at the application, router, and route layers using the middleware keyword argument, combining and executing the middleware defined in each layer. The execution order is always: application, router, and then route.
Auto-generated Swagger Documentation:
- Automatically generates Swagger documentation for each registered route, making it easier to maintain and share API documentation with others. You can view, modify, and extend the autogenerated schema.
Route Tagging:
- Added route tagging, allowing you to categorize routes and easily manage or filter them based on assigned tags. This is used when autogenerating the Swagger documentation to group together similar endpoints.

Cron Scheduling

Oxygen comes with a built-in cron scheduling system that allows you to call endpoints and functions automatically when the cron expression matches the current time.

When a job is scheduled, a new task is created and runs in the background. Each task uses its given cron expression and the current time to determine how long it needs to sleep before it can execute.

The cron parser in Oxygen is based on the same specifications as the one used in Spring. You can find more information about this on the Spring Cron Expressions page.

Cron Expression Syntax

The following is a breakdown of what each parameter in our cron expression represents. While our specification closely resembles the one defined by Spring, it's not an exact 1-to-1 match.

The string has six single space-separated time and date fields:

 ┌───────────── second (0-59)
 │ ┌───────────── minute (0 - 59)
 │ │ ┌───────────── hour (0 - 23)
 │ │ │ ┌───────────── day of the month (1 - 31)
 │ │ │ │ ┌───────────── month (1 - 12) (or JAN-DEC)
 │ │ │ │ │ ┌───────────── day of the week (1 - 7)
 │ │ │ │ │ │          (Monday is 1, Tue is 2... and Sunday is 7)
 │ │ │ │ │ │
 * * * * * *

Partial expressions are also supported, which means that subsequent expressions can be left out (they are defaulted to '*').

# In this example we see only the `seconds` part of the expression is defined. 
# This means that all following expressions are automatically defaulted to '*' expressions
@cron "*/2" function()
    println("runs every 2 seconds")
end

Scheduling Endpoints

The router() function has a keyword argument called cron, which accepts a cron expression that determines when an endpoint is called. Just like the other keyword arguments, it can be reused by endpoints that share routers or be overridden by inherited endpoints.

# execute at 8, 9 and 10 o'clock of every day.
@get router("/cron-example", cron="0 0 8-10 * * *") function(req)
    println("here")
end

# execute this endpoint every 5 seconds (whenever current_seconds % 5 == 0)
every5 = router("/cron", cron="*/5")

# this endpoint inherits the cron expression
@get every5("/first") function(req)
    println("first")
end

# Now this endpoint executes every 2 seconds ( whenever current_seconds % 2 == 0 ) instead of every 5
@get every5("/second", cron="*/2") function(req)
    println("second")
end

Scheduling Functions

In addition to scheduling endpoints, you can also use the new @cron macro to schedule standalone functions. This is useful if you want to run code at specific times without making it visible or callable in the API.

@cron "*/2" function()
    println("runs every 2 seconds")
end

@cron "0 0/30 8-10 * * *" function()
  println("runs at 8:00, 8:30, 9:00, 9:30, 10:00 and 10:30 every day")
end

Starting & Stopping Cron Jobs

When you run serve() or serveparallel(), all registered cron jobs are automatically started. If the server is stopped or killed, all running jobs will also be terminated. You can stop the server and all repeat tasks and cron jobs by calling the terminate() function or manually killing the server with ctrl+C.

In addition, Oxygen provides utility functions to manually start and stop cron jobs: startcronjobs() and stopcronjobs(). These functions can be used outside of a web server as well.

Conclusion

As we wrap up, I want to extend a sincere thank you to each and every one of you for your incredible support, insightful feedback, and active involvement with the project. Your input has played a crucial role in the growth and development of the package, and I look forward to our ongoing collaboration as we team up to make Oxygen.jl even better!

Oxygen.jl: A breath of fresh air for programming web apps in Julia

Nathan Ortega — Mon, 06 Jun 2022 01:01:29 +0000

I'm excited to announce Oxygen.jl, a micro-framework built on top of the HTTP.jl library that's designed to simplify building web applications in Julia.

using Oxygen
using HTTP

@get "/greet" function(req::HTTP.Request)
    return "hello world!"
end

# both path parameters are automatically converted to Float64's 
@get "/multiply/{a}/{b}" function(req, a::Float64, b::Float64)
    return a * b
end

# all objects are automatically deserialized into JSON
@get "/getdata" function()
    return Dict("message" => "hello!")
end

# mount all nested files inside the "content" folder under "/static"
@staticfiles "content" "static"

# start the web server
serve()

Features

Straightforward routing (@get, @post, @put, @patch, @delete and @route macros)
Out-of-the-box JSON serialization & deserialization
Optional type definition support for Path parameters
Helper functions to parse & transform the body of requests & responses
Hosting static files
Built-in multithreading support

Why build another web framework?

That's a great question, why create another package if Julia already has full stack frameworks like Genie.jl that can do just about anything?

My quick answer: most people don't need all features that come with these heavyweight packages. About a month ago, I was one of those people looking to quickly spin up a web server to prototype some ideas.

I wanted something lightweight and straightforward, and I didn't want to spend a lot of time learning a new syntax. Ideally, I wanted something similar to Flask or FastApi but in Julia.

So, I set out to create this package and design a no-nonsense api that would hopefully feel familiar to JS and Python programmers and drive greater adoption in these communities.

Feature Requests

If you have any ideas or feature requests, please feel free to open an issue on the github page!

Julia Community 🟣: Nathan Ortega