Adding license and adjusting readme
This commit is contained in:
Ian Roddis
@@ -2,6 +2,7 @@
|
||||
name = "flexcal"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
license-file = "LICENSE.txt"
|
||||
|
||||
# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
|
||||
|
||||
|
||||
21
LICENSE.txt
Normal file
21
LICENSE.txt
Normal file
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2021 Kinesin Data Technologies Incorporated
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
165
README.md
165
README.md
@@ -1,27 +1,8 @@
|
||||
Introduction
|
||||
============
|
||||
|
||||
Easier job scheduling, supporting:
|
||||
|
||||
- Schedules in a particular timezone
|
||||
- Calendars (defining which days are in scope)
|
||||
- Schedules (defining spans of hours in a day)
|
||||
- Jobs
|
||||
- Given a calendar
|
||||
- And a schedule
|
||||
- Define a pattern of when jobs should run
|
||||
- e.g.
|
||||
- minute = "0,15,30,35", hour = "123"
|
||||
- minute = "0", hour = "*"
|
||||
- minute = "5", frequency = "15" // Start at 5 past the hour, and run every 15 minutes from then
|
||||
|
||||
A job will
|
||||
|
||||
Authorization
|
||||
=============
|
||||
|
||||
ezsched relies on PAM authentication. By default, all objects are owned
|
||||
by the user that submitted them.
|
||||
A flexible calendar structure to support aribtrary and calculated
|
||||
off days.
|
||||
|
||||
Calendars
|
||||
=========
|
||||
@@ -43,147 +24,5 @@ Calendars consist of:
|
||||
- Optional `description`
|
||||
- Optional `observed` attribute that is `Next`, `Prev`, `Closest`, `NoAdjustment` (default)
|
||||
that is in the day of week mask and not also a holiday
|
||||
- A public flag, which if true will make the calendar publicly available
|
||||
- A name, which can contain letters, numbers, dashes, and underscores
|
||||
- They cannot contain dots / periods
|
||||
|
||||
By default, calendars are referred to by their name, but are scoped by
|
||||
the owning user in the format `user.calendar`.
|
||||
|
||||
Users can refer to their own calendars with just the name, other users
|
||||
must access unowned calendars using the fulle `user.calendar` notation.
|
||||
|
||||
Endpoints
|
||||
---------
|
||||
|
||||
```
|
||||
/api/v1
|
||||
/calendars
|
||||
GET -- Retrieve list of calendars and descriptions
|
||||
/calendar/:id
|
||||
GET -- Get the current definition
|
||||
POST -- Create a new calendar
|
||||
PATCH -- Update an existing calendar
|
||||
DELETE -- Delete the named calendar
|
||||
/calendar/:id/:date
|
||||
GET -- Returns true if the date is in the calendar
|
||||
/calendar/:id/:from/:to
|
||||
GET -- Return the list of valid dates between :from and :to, inclusive.
|
||||
:from and :to are in the ISO-8601 date format (YYYY-MM-DD)
|
||||
```
|
||||
|
||||
Calendar `:id`s are alphanumeric strings without spaces (e.g. `USHolidays`).
|
||||
|
||||
Encoding
|
||||
--------
|
||||
|
||||
A JSON definition for a calendar looks as follows:
|
||||
|
||||
```json
|
||||
{
|
||||
"description": "Long description",
|
||||
"dow_list": ["Mon","Tue","Wed","Thu","Fri", "Sat", "Sun"],
|
||||
"public": true,
|
||||
"exclude": [
|
||||
{
|
||||
"date": "2021-01-01",
|
||||
"description": "New Years Day"
|
||||
},
|
||||
{
|
||||
"month": "January",
|
||||
"day": 17,
|
||||
"observed": "closest",
|
||||
"description": "Martin Luther King Day"
|
||||
},
|
||||
{
|
||||
"month": "January",
|
||||
"dow": ["Mon"],
|
||||
"offset": "-1",
|
||||
"observed": "closest",
|
||||
"description": "Final Monday Margarita Day"
|
||||
},
|
||||
]
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Inheritance
|
||||
-----------
|
||||
|
||||
Calendars can inherit from other calendars. The result will be a union
|
||||
of the sets of days. For instance, a calendar of vacations could inherit
|
||||
from a calendar of holidays.
|
||||
|
||||
```json
|
||||
{
|
||||
"description": "Personal calendar days",
|
||||
"inherits": [
|
||||
"company/USHolidays",
|
||||
"company/CompanyHolidays"
|
||||
],
|
||||
"exclude": [
|
||||
{
|
||||
"date": "2021-05-01",
|
||||
"description": "My gerbil's birthday"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Job
|
||||
===
|
||||
|
||||
Jobs are tasks that must be run on a schedule. Schedules are defined
|
||||
using a calendar, a start time, and an optional frequency.
|
||||
|
||||
Jobs are identified by a name that can contain letters, numbers, dashes,
|
||||
and underscores. Just like calendars, jobs can be reffered to using a
|
||||
`user.job` notation.
|
||||
|
||||
By default, Jobs are run as the user that submitted them.
|
||||
|
||||
```json
|
||||
{
|
||||
"description": "Description of job",
|
||||
"calendar": "US Holidays",
|
||||
"timezone": "Atlantic/Reykjavik",
|
||||
"schedules": [
|
||||
{
|
||||
"start": {
|
||||
"minute": "5",
|
||||
"hour": "*",
|
||||
},
|
||||
"frequency": "15m"
|
||||
}
|
||||
],
|
||||
"command": {
|
||||
},
|
||||
"environment": {
|
||||
},
|
||||
"mailto": [
|
||||
"oncall@company.com"
|
||||
],
|
||||
"public_acl": "rwx"
|
||||
}
|
||||
```
|
||||
|
||||
The `public_acl` is a string that defines how the non-owning users can
|
||||
access the job: `r`ead it, `w`rite its defintiion, or e`x`ecute it.
|
||||
|
||||
Endpoints
|
||||
---------
|
||||
|
||||
```
|
||||
/api/v1
|
||||
/jobs
|
||||
GET -- Retrieve list of jobs and descriptions
|
||||
/job/:id
|
||||
GET -- Get the current definition
|
||||
POST -- Create a new job
|
||||
PATCH -- Update an existing job
|
||||
DELETE -- Delete the job
|
||||
/job/:id/run
|
||||
GET -- Force a run of the job immediately
|
||||
/job/:id/history
|
||||
GET -- Retrieve the run history and results
|
||||
```
|
||||
|
||||
@@ -192,8 +192,6 @@ pub struct Calendar {
|
||||
#[serde(default = "default_dow_set")]
|
||||
pub dow: HashSet<Weekday>,
|
||||
#[serde(default)]
|
||||
pub public: bool,
|
||||
#[serde(default)]
|
||||
pub exclude: Vec<DateSpec>,
|
||||
#[serde(default)]
|
||||
pub inherits: Vec<String>,
|
||||
@@ -315,7 +313,6 @@ mod tests {
|
||||
let cal = Calendar {
|
||||
description: "Test description".to_owned(),
|
||||
dow: HashSet::from([Mon, Tue, Wed, Thu, Fri]),
|
||||
public: false,
|
||||
exclude: vec![
|
||||
DateSpec::DayOfMonth {
|
||||
month: December,
|
||||
@@ -354,7 +351,6 @@ mod tests {
|
||||
let cal = Calendar {
|
||||
description: "Test description".to_owned(),
|
||||
dow: HashSet::from([Mon, Tue, Wed, Thu, Fri]),
|
||||
public: false,
|
||||
exclude: vec![
|
||||
DateSpec::DayOfMonth {
|
||||
month: December,
|
||||
@@ -399,7 +395,6 @@ mod tests {
|
||||
{
|
||||
"description": "Long description",
|
||||
"dow": ["Mon","Tue","Wed","Thu","Fri", "Sat", "Sun"],
|
||||
"public": true,
|
||||
"exclude": [
|
||||
{
|
||||
"type": "SpecificDate",
|
||||
|
||||
Reference in New Issue
Block a user