Merge pull request #161 from sebadob/create-contribution-guide

Create a contribution and getting started guide
sebadob · Nov 10, 2023 · 7c38142 · 7c38142
2 parents 0ead2f8 + b66f4c0
commit 7c38142
Show file tree

Hide file tree

Showing 9 changed files with 97 additions and 2 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,76 @@
+# Contributing to Rauthy
+
+This document should help you to contribute to Rauthy and setting up your local dev environment.
+
+## Guidelines for writing code
+
+- **Performance and footprint matters**. If you write code, think about performance and especially memory footprint.
+For instance, avoid cloning values around when borrowing works fine too, or avoid allocating new memory in general,
+when you do not need to. The final performance optimizations have not been done yet, but everything we can do already
+is appreciated.
+- **Use safe Rust only**. All crates forbid the usage of unsafe code globally. We do not care about the very last tiny
+bit of performance in special places when we would give up memory safety for that.
+- **Stick to idiomatic Rust**. Stick to idiomatic Rust semantics and always use rust the `cargo fmt` for your code.
+- **Use meaningful names**. For instance, a function that returns a `bool` should have a name like `is_admin` or
+`has_access`. All functions that do any database lookup currently use keywords like `find`, `create`, `update`, `save`
+and `delete` and have their own `impl` block for the structs to be "easily" interchangeable. Basically, you should have
+a general idea what a function does if you just read its name.
+
+## Getting Started
+
+The most important thing to compile the code is obviously `rust` and `cargo`. The frontend part is based on
+[svelte](https://svelte.dev/), which means you need `npm` as well. Working with this project is fully set up with
+[just](https://github.com/casey/just), which is a modern alternative to `make`, written in Rust.
+
+### Prerequisites 
+
+- Rust installed and `cargo` available
+- Node / `npm` available
+- `docker` available, if you want to build images
+- [just](https://github.com/casey/just) installed
+- BASH (no cmd.exe or powershell) - when you are on windows, you can use something like Git BASH
+
+### Get it up and running
+
+Once prerequisites are met, the rest should be really simple:
+
+1. Install node-modules
+    - `cd frontend`
+    - `npm install`
+2. If this is a fresh pull, build the UI once to populate the `templates/html`
+    - `just build-ui`
+3. Create and migrate SQLite to make the compile-time checked queries happy
+    - `just migrate-sqlite`
+
+This should be it with the setup part. If you just want to work on the backend, you only need:
+
+`just run-sqlite`
+
+If you want to work on the frontend too, in another terminal:
+
+`just run-ui`
+
+There is only one thing about the UI in local dev. The way the static file adapter from svelte is set up right now,
+you will not be able to access http://localhost:5173/auth/v1, you actually would need to append `/index` here once.
+The rest works just the same and as expected: http://localhost:5173/auth/v1/index
+
+As long as you don't use passkeys, it should work right away. If you however want to test passkeys with the local
+dev ui, you need to adjust the port for `RP_ORIGIN` in the `rauthy.cfg`.
+
+## Before Submitting a PR
+
+This project does not have any actions and automatic pipelines set up yet.  
+This means, that you should make sure, that `clippy` does not give any warnings for your code and that all the test 
+cases are fine.
+
+As long as you do not have done anything like feature dependant queries and use different `query!` macro depending
+on the uses features, you are fine with just executing `clippy` and tests for sqlite only:
+
+- `just clippy-sqlite`
+- `just test-sqlite`
+
+> One thing about `just test-sqlite`: This does build the backend, start it in a background task and then executes
+> all tests incl integration tests. However, is uses `set -euxo pipefail` inside the script, which make it fail if
+> any test case fails. The way the script works, this does not kill the background task currently, which you have to do
+> manually. The reasons this option is set is that it would otherwise be possible to execute the whole build pipeline
+> and oversee failing test cases. If you are working on tests locally, you can out-comment this line temporarily.
diff --git a/justfile b/justfile
@@ -64,6 +64,12 @@ docker-buildx-setup:
     docker buildx inspect rauthy_builder
 
 
+# Just uses `cargo fmt --all`
+fmt:
+    #!/usr/bin/env bash
+    cargo fmt --all
+
+
 # Force-pulls the latest `cross` docker image for cross-compilation
 pull-latest-cross:
     #!/usr/bin/env bash
@@ -282,7 +288,7 @@ release:
 
 
 # publishes the application images - full pipeline incl clippy and testing
-publish: pull-latest-cross build-docs build-ui build-sqlite build-postgres
+publish: pull-latest-cross build-docs build-ui fmt build-sqlite build-postgres
     #!/usr/bin/env bash
     set -euxo pipefail
 

diff --git a/rauthy-common/src/lib.rs b/rauthy-common/src/lib.rs
@@ -1,4 +1,7 @@
 // Copyright 2023 Sebastian Dobe <sebastiandobe@mailbox.org>
+
+#![forbid(unsafe_code)]
+// needed because the lazy_static! initialization of constants grew quite a bit
 #![recursion_limit = "256"]
 
 use std::str::FromStr;

diff --git a/rauthy-handlers/src/lib.rs b/rauthy-handlers/src/lib.rs
@@ -1,5 +1,7 @@
 // Copyright 2023 Sebastian Dobe <sebastiandobe@mailbox.org>
 
+#![forbid(unsafe_code)]
+
 use actix_web::dev::ServiceRequest;
 use actix_web::{web, HttpRequest, HttpResponse};
 use rauthy_common::constants::{COOKIE_MFA, PROXY_MODE};

diff --git a/rauthy-main/src/main.rs b/rauthy-main/src/main.rs
@@ -1,5 +1,7 @@
 // Copyright 2023 Sebastian Dobe <sebastiandobe@mailbox.org>
 
+#![forbid(unsafe_code)]
+
 use actix_web::rt::System;
 use actix_web::{middleware, web, App, HttpServer};
 use actix_web_prom::PrometheusMetricsBuilder;

diff --git a/rauthy-main/tests/zza_handler_cust_attrs.rs b/rauthy-main/tests/zza_handler_cust_attrs.rs
@@ -1,5 +1,6 @@
 use crate::common::{get_auth_headers, get_backend_url, get_token_set};
 use rauthy_common::utils::extract_token_claims_unverified;
+use rauthy_models::entity::jwk::JwkKeyPairAlg;
 use rauthy_models::entity::user_attr::UserAttrConfigEntity;
 use rauthy_models::request::{
     ScopeRequest, UpdateClientRequest, UserAttrConfigRequest, UserAttrValueRequest,
@@ -11,7 +12,6 @@ use rauthy_models::response::{
 use rauthy_models::JwtAccessClaims;
 use serde_json::Value;
 use std::error::Error;
-use rauthy_models::entity::jwk::JwkKeyPairAlg;
 
 mod common;
 

diff --git a/rauthy-models/src/lib.rs b/rauthy-models/src/lib.rs
@@ -1,5 +1,7 @@
 // Copyright 2023 Sebastian Dobe <sebastiandobe@mailbox.org>
 
+#![forbid(unsafe_code)]
+
 use crate::entity::sessions::Session;
 use actix_web::http::header::{HeaderName, HeaderValue};
 use actix_web::HttpRequest;

diff --git a/rauthy-notify/src/lib.rs b/rauthy-notify/src/lib.rs
@@ -1,5 +1,7 @@
 // Copyright 2023 Sebastian Dobe <sebastiandobe@mailbox.org>
 
+#![forbid(unsafe_code)]
+
 use async_trait::async_trait;
 use rauthy_common::constants::RAUTHY_VERSION;
 use rauthy_common::error_response::ErrorResponse;

diff --git a/rauthy-service/src/lib.rs b/rauthy-service/src/lib.rs
@@ -1,5 +1,7 @@
 // Copyright 2023 Sebastian Dobe <sebastiandobe@mailbox.org>
 
+#![forbid(unsafe_code)]
+
 pub mod auth;
 pub mod client;
 pub mod encryption;