From ed489914a7287c82dd4cd11b37d815ec66bf8dd7 Mon Sep 17 00:00:00 2001
From: Ian Roddis <tech@kinesin.ca>
Date: Thu, 2 Dec 2021 13:52:11 -0400
Subject: [PATCH] Initial commit of spec

---
 .gitignore  |   1 +
 Cargo.toml  |   8 +++
 README.md   | 188 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 src/main.rs |   3 +
 4 files changed, 200 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 Cargo.toml
 create mode 100644 README.md
 create mode 100644 src/main.rs

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..ea8c4bf
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+/target
diff --git a/Cargo.toml b/Cargo.toml
new file mode 100644
index 0000000..030f0da
--- /dev/null
+++ b/Cargo.toml
@@ -0,0 +1,8 @@
+[package]
+name = "ezsched"
+version = "0.1.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2d98f4c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,188 @@
+Introduction
+============
+
+Easier job scheduling, supporting:
+
+- Schedules in a particular timezone
+- Calendars
+
+Authorization
+=============
+
+ezsched relies on PAM authentication. By default, all objects are owned
+by the user that submitted them.
+
+Calendars
+=========
+
+Definition
+----------
+
+Calendars consist of:
+
+- Day of week list
+- Date Exclusion List
+  - Dates are defined as:
+    - One of
+      - YYYY-MM-DD
+        - Add a specific date to a calendar's exclusion list
+      - Month and Day
+      - Month, Day of week, and Number (e.g. 2nd Friday)
+        - Number can be relative, so 1 is first, -1 is last
+    - Optional `description`
+    - Optional `observed` attribute that is `next`, `prev`, `closest`, `none` (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": ["M","T","W","R","F"],
+  "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": "M",
+      "-1",
+      "observed": "closest",
+      "description": "Final Monday Margarita Day"
+      },
+    ]
+  ]
+}
+```
+
+Letter codes are:
+
+| Day of Week | Letter |
+|-------------|--------|
+| Monday      | M      |
+| Tuesday     | T      |
+| Wednesday   | W      |
+| Thursday    | **R**  |
+| Friday      | F      |
+| Saturday    | S      |
+| Sunday      | U      |
+
+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",
+  "schedule": {
+    "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
+```
diff --git a/src/main.rs b/src/main.rs
new file mode 100644
index 0000000..e7a11a9
--- /dev/null
+++ b/src/main.rs
@@ -0,0 +1,3 @@
+fn main() {
+    println!("Hello, world!");
+}