diff --git a/README.md b/README.md index 1b44745..e59204f 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,6 @@ Align your schedules to find the perfect time that works for everyone. Licensed under the GNU GPLv3. -Crab Fit - Use your availability to find a time that works for everyone | Product Hunt - ## Contributing ### ⭐️ Bugs or feature requests @@ -17,14 +15,13 @@ If you speak a language other than English and you want to help translate Crab F ## Setup -1. Clone the repo. -2. Run `yarn` in both backend and frontend folders. -3. Run `yarn dev` in the backend folder to start the API. **Note:** you will need a google cloud app set up with datastore enabled and set your `GOOGLE_APPLICATION_CREDENTIALS` environment variable to your service key path. -4. Run `yarn dev` in the frontend folder to start the frontend. +1. Clone the repo and ensure you have `node`, `yarn` and `rust` installed on your machine. +2. Run `yarn` in `frontend` folder to install dependencies, then `yarn dev` to start the dev server. +3. Run `cargo run` in the `api` folder to start the API. ### 🔌 Browser extension -The browser extension in `crabfit-browser-extension` can be tested by first running the frontend, and changing the iframe url in the extension's `popup.html` to match the local Crab Fit. Then it can be loaded as an unpacked extension in Chrome to test. +The browser extension in `browser-extension` can be tested by first running the frontend, and changing the iframe url in the extension's `popup.html` to match the local Crab Fit. Then it can be loaded as an unpacked extension in Chrome to test. ## Deploy @@ -34,4 +31,4 @@ To deploy cron jobs (i.e. monthly cleanup of old events), run `gcloud app deploy ### 🔌 Browser extension -Compress everything inside the `crabfit-browser-extension` folder and use that zip to deploy using Chrome web store and Mozilla Add-on store. +Compress everything inside the `browser-extension` folder and use that zip to deploy using Chrome web store and Mozilla Add-on store. diff --git a/backend/.gitignore b/api/.gitignore similarity index 100% rename from backend/.gitignore rename to api/.gitignore diff --git a/backend/Cargo.lock b/api/Cargo.lock similarity index 100% rename from backend/Cargo.lock rename to api/Cargo.lock diff --git a/backend/Cargo.toml b/api/Cargo.toml similarity index 97% rename from backend/Cargo.toml rename to api/Cargo.toml index dadb128..0d5ff31 100644 --- a/backend/Cargo.toml +++ b/api/Cargo.toml @@ -1,5 +1,5 @@ [package] -name = "crabfit_backend" +name = "crabfit-api" description = "API for Crab Fit" license = "GPL-3.0-only" version = "2.0.0" diff --git a/api/README.md b/api/README.md new file mode 100644 index 0000000..3b9eade --- /dev/null +++ b/api/README.md @@ -0,0 +1,26 @@ +# Crab Fit API + +This is the API for Crab Fit, written in Rust. It uses the [axum](https://crates.io/crates/axum) framework to run a HTTP server, and supports multiple storage adaptors. + +## API docs + +OpenAPI compatible API docs are generated using [utoipa](https://crates.io/crates/utoipa). You can visit them at [https://api.crab.fit/docs](https://api.crab.fit/docs). + +## Storage adaptors + +| Adaptor | Works with | +| ------- | ---------- | +| `memory-adaptor` | Stores data in memory | +| `sql-adaptor` | Postgres, MySQL, SQLite | +| `datastore-adaptor` | Google Datastore | + +To choose an adaptor, specify it in the `features` when compiling, e.g. `cargo run --features sql-adaptor`. + +Some adaptors require environment variables to be set. You can specify them in a `.env` file and they'll be loaded in using [dotenvy](https://crates.io/crates/dotenvy). See a specific adaptor's readme for more information. + +> **Note** +> `memory-adaptor` is the default if no features are specified. Ensure you specify a different adaptor when deploying. + +### Adding an adaptor + +See [adding an adaptor](adaptors/README.md#adding-an-adaptor) in the adaptors readme. diff --git a/api/adaptors/README.md b/api/adaptors/README.md new file mode 100644 index 0000000..f1fbcaa --- /dev/null +++ b/api/adaptors/README.md @@ -0,0 +1,21 @@ +# Crab Fit Storage Adaptors + +This directory contains sub-crates that connect Crab Fit to a database of some sort. For a list of available adaptors, see the [api readme](../README.md). + +## Adding an adaptor + +The suggested flow is copying an existing adaptor, such as `memory`, and altering the code to work with your chosen database. + +Note, you will need to have the following crates as dependencies in your adaptor: + +- `common`
Includes a trait for implementing your adaptor, as well as structs your adaptor needs to return. +- `async-trait`
Required because the trait from `common` uses async functions, make sure you include `#[async_trait]` above your trait implementation. + +Once you've created the adaptor, you'll need to make sure it's included as a dependency in the root [`Cargo.toml`](../Cargo.toml), and add a feature flag with the same name. Make sure you also document the new adaptor in the [api readme](../README.md). + +Finally, add a new version of the `create_adaptor` function in the [`adaptors.rs`](../src/adaptors.rs) file that will only compile if the specific feature flag you added is set. Don't forget to add a `not` version of the feature to the default memory adaptor function at the bottom of the file. + +## FAQ + +Why is it spelt "adaptor" and not "adapter"? +> The maintainer lives in Australia, where it's usually spelt "adaptor" 😎 diff --git a/backend/adaptors/datastore/Cargo.toml b/api/adaptors/datastore/Cargo.toml similarity index 84% rename from backend/adaptors/datastore/Cargo.toml rename to api/adaptors/datastore/Cargo.toml index bc6764b..da37e8c 100644 --- a/backend/adaptors/datastore/Cargo.toml +++ b/api/adaptors/datastore/Cargo.toml @@ -7,6 +7,7 @@ edition = "2021" async-trait = "0.1.68" chrono = "0.4.24" common = { path = "../../common" } +# Uses custom version of google-cloud that has support for NULL values google-cloud = { git = "https://github.com/GRA0007/google-cloud-rs.git", features = ["datastore", "derive"] } serde = "1.0.163" serde_json = "1.0.96" diff --git a/api/adaptors/datastore/README.md b/api/adaptors/datastore/README.md new file mode 100644 index 0000000..ca3a3d6 --- /dev/null +++ b/api/adaptors/datastore/README.md @@ -0,0 +1,13 @@ +# Google Datastore Adaptor + +This adaptor works with [Google Cloud Datastore](https://cloud.google.com/datastore). Please note that it's compatible with Firestore in Datastore mode, but not with Firestore. + +## Environment + +To use this adaptor, make sure you have the `GCP_CREDENTIALS` environment variable set to your service account credentials in JSON format. See [this page](https://developers.google.com/workspace/guides/create-credentials#service-account) for info on setting up a service account and generating credentials. + +Example: + +```env +GCP_CREDENTIALS='{"type":"service_account","project_id":"my-project"}' +``` diff --git a/backend/adaptors/datastore/src/lib.rs b/api/adaptors/datastore/src/lib.rs similarity index 100% rename from backend/adaptors/datastore/src/lib.rs rename to api/adaptors/datastore/src/lib.rs diff --git a/backend/adaptors/memory/Cargo.toml b/api/adaptors/memory/Cargo.toml similarity index 100% rename from backend/adaptors/memory/Cargo.toml rename to api/adaptors/memory/Cargo.toml diff --git a/api/adaptors/memory/README.md b/api/adaptors/memory/README.md new file mode 100644 index 0000000..c7a43e4 --- /dev/null +++ b/api/adaptors/memory/README.md @@ -0,0 +1,6 @@ +# Memory Adaptor + +This adaptor stores everything in memory, and all data is lost when the API is stopped. Useful for testing. + +> **Warning** +> Do not use this adaptor in production! diff --git a/backend/adaptors/memory/src/lib.rs b/api/adaptors/memory/src/lib.rs similarity index 100% rename from backend/adaptors/memory/src/lib.rs rename to api/adaptors/memory/src/lib.rs diff --git a/backend/adaptors/sql/Cargo.toml b/api/adaptors/sql/Cargo.toml similarity index 100% rename from backend/adaptors/sql/Cargo.toml rename to api/adaptors/sql/Cargo.toml diff --git a/api/adaptors/sql/README.md b/api/adaptors/sql/README.md new file mode 100644 index 0000000..0fcb334 --- /dev/null +++ b/api/adaptors/sql/README.md @@ -0,0 +1,13 @@ +# SQL Adaptor + +This adaptor works with [Postgres](https://www.postgresql.org/), [MySQL](https://www.mysql.com/) or [SQLite](https://sqlite.org/index.html) databases. + +## Environment + +To use this adaptor, make sure you have the `DATABASE_URL` environment variable set to the database url for your chosen database. + +Example: + +```env +DATABASE_URL="postgresql://username:password@localhost:5432/crabfit" +``` diff --git a/backend/adaptors/sql/src/entity/event.rs b/api/adaptors/sql/src/entity/event.rs similarity index 100% rename from backend/adaptors/sql/src/entity/event.rs rename to api/adaptors/sql/src/entity/event.rs diff --git a/backend/adaptors/sql/src/entity/mod.rs b/api/adaptors/sql/src/entity/mod.rs similarity index 100% rename from backend/adaptors/sql/src/entity/mod.rs rename to api/adaptors/sql/src/entity/mod.rs diff --git a/backend/adaptors/sql/src/entity/person.rs b/api/adaptors/sql/src/entity/person.rs similarity index 100% rename from backend/adaptors/sql/src/entity/person.rs rename to api/adaptors/sql/src/entity/person.rs diff --git a/backend/adaptors/sql/src/entity/prelude.rs b/api/adaptors/sql/src/entity/prelude.rs similarity index 100% rename from backend/adaptors/sql/src/entity/prelude.rs rename to api/adaptors/sql/src/entity/prelude.rs diff --git a/backend/adaptors/sql/src/entity/stats.rs b/api/adaptors/sql/src/entity/stats.rs similarity index 100% rename from backend/adaptors/sql/src/entity/stats.rs rename to api/adaptors/sql/src/entity/stats.rs diff --git a/backend/adaptors/sql/src/lib.rs b/api/adaptors/sql/src/lib.rs similarity index 100% rename from backend/adaptors/sql/src/lib.rs rename to api/adaptors/sql/src/lib.rs diff --git a/backend/adaptors/sql/src/migration/m01_setup_tables.rs b/api/adaptors/sql/src/migration/m01_setup_tables.rs similarity index 100% rename from backend/adaptors/sql/src/migration/m01_setup_tables.rs rename to api/adaptors/sql/src/migration/m01_setup_tables.rs diff --git a/backend/adaptors/sql/src/migration/mod.rs b/api/adaptors/sql/src/migration/mod.rs similarity index 100% rename from backend/adaptors/sql/src/migration/mod.rs rename to api/adaptors/sql/src/migration/mod.rs diff --git a/backend/common/Cargo.toml b/api/common/Cargo.toml similarity index 100% rename from backend/common/Cargo.toml rename to api/common/Cargo.toml diff --git a/api/common/README.md b/api/common/README.md new file mode 100644 index 0000000..3ca3179 --- /dev/null +++ b/api/common/README.md @@ -0,0 +1,3 @@ +# Common + +This crate contains the [adaptor trait](./src/adaptor.rs), and structs that are used by it. These are separated into their own crate so that the root crate and the adaptors can import from it without causing a circular dependency. diff --git a/backend/common/src/adaptor.rs b/api/common/src/adaptor.rs similarity index 100% rename from backend/common/src/adaptor.rs rename to api/common/src/adaptor.rs diff --git a/backend/common/src/event.rs b/api/common/src/event.rs similarity index 100% rename from backend/common/src/event.rs rename to api/common/src/event.rs diff --git a/backend/common/src/lib.rs b/api/common/src/lib.rs similarity index 100% rename from backend/common/src/lib.rs rename to api/common/src/lib.rs diff --git a/backend/common/src/person.rs b/api/common/src/person.rs similarity index 100% rename from backend/common/src/person.rs rename to api/common/src/person.rs diff --git a/backend/common/src/stats.rs b/api/common/src/stats.rs similarity index 100% rename from backend/common/src/stats.rs rename to api/common/src/stats.rs diff --git a/backend/src/adaptors.rs b/api/src/adaptors.rs similarity index 100% rename from backend/src/adaptors.rs rename to api/src/adaptors.rs diff --git a/backend/src/docs.rs b/api/src/docs.rs similarity index 100% rename from backend/src/docs.rs rename to api/src/docs.rs diff --git a/backend/src/errors.rs b/api/src/errors.rs similarity index 100% rename from backend/src/errors.rs rename to api/src/errors.rs diff --git a/backend/src/main.rs b/api/src/main.rs similarity index 100% rename from backend/src/main.rs rename to api/src/main.rs diff --git a/backend/src/payloads.rs b/api/src/payloads.rs similarity index 100% rename from backend/src/payloads.rs rename to api/src/payloads.rs diff --git a/backend/src/res/adjectives.json b/api/src/res/adjectives.json similarity index 100% rename from backend/src/res/adjectives.json rename to api/src/res/adjectives.json diff --git a/backend/src/res/crabs.json b/api/src/res/crabs.json similarity index 100% rename from backend/src/res/crabs.json rename to api/src/res/crabs.json diff --git a/backend/src/routes/event.rs b/api/src/routes/event.rs similarity index 100% rename from backend/src/routes/event.rs rename to api/src/routes/event.rs diff --git a/backend/src/routes/mod.rs b/api/src/routes/mod.rs similarity index 100% rename from backend/src/routes/mod.rs rename to api/src/routes/mod.rs diff --git a/backend/src/routes/person.rs b/api/src/routes/person.rs similarity index 100% rename from backend/src/routes/person.rs rename to api/src/routes/person.rs diff --git a/backend/src/routes/stats.rs b/api/src/routes/stats.rs similarity index 100% rename from backend/src/routes/stats.rs rename to api/src/routes/stats.rs