zomtir / cptserver

ABOUT

This is the server application for providing an API for the cptclient. CPT stands for Course Participation Tracker.

PREPARATIONS

The server requires a database with the structure described Database.sql. The easiest way to setup is to setup a MariaDB database. Adapt the names to your liking.

CREATE USER 'cptdb-user'@'localhost' IDENTIFIED BY 'cptdb-password';
CREATE DATABASE cptdb;
GRANT ALL PRIVILEGES ON cptdb.* TO 'cptdb-user'@'localhost';

Then import the Database.sql file via phymyadmin or use the CML. You will be promted to enter the 'cptdb-password'.

mariadb -u cptdb-user -p cptdb < Database.sql

Finally, set up a config file called cptserver.toml for the server containing the database details. You can use cptserver.template.toml as template. 3306 is usually the default port.

db_server = 'localhost'
db_port = 3306
db_database = 'cptdb'
db_user = 'cptdb-user'
db_password = 'cptdb-password'

To create an initial admin user account, also include an cpt_admin in cptserver.toml. He has all right and requires no password. Do remove this line as soon as you are done with the initial user/group setup.

cpt_admin = 'admin'

Compiling and executing the application for developement is the usualy cargo workflow.

# Format your code if you made changes
cargo fmt
# Run a sanity check on your changes
cargo clippy
# Build the application
cargo build
# Run the application
cargo run

RELEASES

When you make a new release, this is the targeted procedure.

The versioning scheme is MAJOR.MINOR.PATCH, increment the:

• MAJOR version when you make substantial API changes or core reworks
• MINOR version when you make any API changes
• PATCH version when you make backward compatible changes

As long as the MAJOR release is 0.x, it is considered a pre-release. The API and feature set might be incomplete and unstable.

# Tag the commit with a release tag and a 'v' prefix.
# The `PATCH` version is omitted for the `.0` increment.
git tag v0.7

# Adapt the Cargo toml file
> version = "0.7.0"

PRODUCTION

To build a binary for production, choose a reliable version and build it with the --release flag.

cargo build --release

The binary can be found at ./target/release/cptserver.

There is also a systemd unit file (cptserver.service) with the assumption that you have your binary installed at /opt/cptserver/.

LICENSE

The code is dedicated to the Public Domain.

CONTRIBUTING

Contributing to the project implies a copyright release as stated in the Waiver unless stated otherwise.

You are very welcome to explicitly state your approval with a simple statement such as Dedicated to Public Domain in your patches. You can also sign the Waiver with GPG while listing yourself as Author.

# Generate a GPG key
gpg --full-generate-key
# Sign the waiver
gpg --no-version --armor --sign WAIVER.md
# Copy the signature
cat WAIVER.md.asc
# Optionally export your public key and add it to your Github account and/or a keyserver.
gpg --list-keys
gpg --armor --export <KEYID>

cptserver's Issues

Correctly assign read/write permissions to API calls

Currently everything is gated by write permissions

Inventory API

• ItemCategory
  • createItemCategory(name, description)
  • editItemCategory
  • deleteItemCategory
• Item
  • createItem(name, category)
  • editItem
  • deleteItem
• ClubInventory
  • addItem(club, item, count)
  • removeItem(club, item, count)
  • transferItem(club, item, user, club_id (borrow/ownership flag), date) → possession_id
• UserPossessions
  • cancelTransfer(possession_id) → back to
  • ownTransfer(possession_id) → borrow = null
  • deletePossession(possession_id)

Club Member Statistik for Association Info

|User|Association Number | Team Permission (Date) | Solo Permission (Date) |

Move static behaviour configs to the runtime toml file

Many settings like slot duration rounding are currently configured statically at compile time at config.rs.

Make them available via CptServer.toml.

Attach and decouple an event from a course

Proposal of two new mechanisms:

1. /admin/event_course_add + /admin/event_course_remove

requires both right_event_write and right_course_write

2. /owner/event_course_add + /owner/event_course_remove

requires to be event owner and to be course moderator.

Helper and supervisor role for events

Currently there are owners and participants.

• Participants are self-explanatory
• Helpers support the event but have no core responsibility
• Supervisors can edit participants and add other supervisors
• Owners should be able to remove supervisors

Maybe a role system would make more sense at some point.

Add event registrations

Add event registrations.

Should the registration be per presence (A) or per role (B)?

A) event_registrations
B) event_participant_registrations, event_helper_registrations, event_owner_registrations

• Status of null + three enums: NULL (default) / YES / UNDECIDED / NO

Server action log file

Add a log file for API interactions.

Incoherent owner role for events

If you add yourself as "owner" to an event, this either means:

• you take responsibility and are present
• you are able distribute responsibility

If you are in charge to manage an event, but cannot physically attend, this is a conflict.

Add setup for initial admin user

An initial user account is necessary.

Because user permissions are dependent on a group, also add an initial "Administrators" groups

Split the active attribute from the slot status enum

Change slots.status to "DRAFT,PENDING,ACCEPTED,REJECTED" with another boolean slots.active

Potentionally include the erroneous call stack or API origin in the function result

The error could contain the origin of the error for easier debugging. That way it is possible to debug bottom up by inserting debug info in the function that throws the error to find out which call delivered the faulty info. A full call stack log would make this even easier.

use crate::Error;
use rocket::http::uri::Origin;
    pub fn does_user_exist(origin: &Origin) -> Result<User, Error> {
    match user_exists {
        false => Err(Error::user_missing(origin.path())),
        true => Ok(user),
}

Implement Unit Tests

That at least some code can be covered by cargo test.

Consistent SQL queries with a test DB needs to be evaluated, especially in a CI context.