docs: generate with rustdocs (#21)

.cargo/config.toml

@@ -0,0 +1,2 @@
+[build]
+rustdocflags = ["--extend-css=assets/docs.css", "--default-theme=ayu"]

.github/workflows/continuous-integration.yml

@@ -32,7 +32,7 @@ jobs:
             ~/.cargo/registry/cache/
             ~/.cargo/git/db/
             target/
-          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          key: ${{ runner.os }}-cargo-release-${{ hashFiles('**/Cargo.lock') }}
       - name: Build
         run: cargo build --release
       - name: Format Check

.github/workflows/docs.yml

@@ -0,0 +1,62 @@
+name: Docs
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+concurrency:
+  group: docs
+  cancel-in-progress: false
+
+
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      deployments: write
+    steps:
+      - name: Checkout Project
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4
+
+      - name: Stable Rust
+        uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: stable
+
+      - name: Cargo Cache
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/bin/
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+            target/
+          key: ${{ runner.os }}-cargo-debug-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Clean docs folder
+        run: cargo clean --doc
+
+      - name: Build docs
+        run: cargo doc --no-deps
+
+      - name: Add redirect
+        run: echo '<meta http-equiv="refresh" content="0;url=autopulse/index.html">' > target/doc/index.html
+
+      - name: Remove lock file
+        run: rm target/doc/.lock
+
+      - name: Publish to Cloudflare Pages
+        uses: dan-online/pages-action@main
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          projectName: autopulse
+          directory: target/doc
+          gitHubToken: ${{ secrets.GITHUB_TOKEN }}
+          productionBranch: main

README.md

@@ -16,6 +16,8 @@
     <a href="https://github.com/dan-online/autopulse/issues">Report Bug</a>
     ·
     <a href="https://github.com/dan-online/autopulse/issues">Request Feature</a>
+    .
+    <a href="https://autopulse.pages.dev/">Documentation</a>
   </p>
 </div>
 
@@ -74,7 +76,20 @@ $ docker run -d --net autopulse -e AUTOPULSE__APP__DATABASE_URL=sqlite://databas
 $ docker run -d --net autopulse -e AUTOPULSE__APP__DATABASE_URL=sqlite://:memory: --name autopulse danonline/autopulse
 ```
 
-### Configuration
+### Documentation
+
+All the documentation can be found [on the website](https://autopulse.pages.dev/)
+
+Here's some quick links:
+
+- [Settings](https://autopulse.pages.dev/autopulse/utils/settings/)
+- [Targets](https://autopulse.pages.dev/autopulse/service/targets/)
+- [Triggers](https://autopulse.pages.dev/autopulse/service/triggers/)
+- [Webhooks](https://autopulse.pages.dev/autopulse/service/webhooks/)
+
+### Quick Start
+
+#### Configuration
 
 autopulse requires a configuration file to run. By default, it looks for `config.toml` in the current working directory. You can override the [default values](default.toml) using [a config file](example/config.toml) or by [setting environment variables](example/docker-compose.yml) in the format of: ``AUTOPULSE__{SECTION}__{KEY}``. 
 
@@ -84,7 +99,7 @@ An example has been provided in the [example](example) directory
 
 > Note: You can provide the config with `json`, `toml`, `yaml`, `json5`, `ron`, or `ini` format
 
-#### Authorization
+##### Authorization
 
 autopulse uses basic authorization for the API. You can set the username and password in the config file or by setting the `AUTOPULSE__AUTH__USERNAME` and `AUTOPULSE__AUTH__PASSWORD` environment variables.
 
@@ -153,14 +168,6 @@ targets:
     raw: "echo $FILE_PATH >> list.txt"
 ```
 
-#### Path Checking
-
-By enabling path checking either by setting `check_path` to `true` in the config file or by setting the `AUTOPULSE__OPTS__CHECK_PATH` environment variable, autopulse will check if the path exists before updating targets.
-
-```yaml
-opts:
-  check_path: true
-```
 
 #### Manual
 
@@ -170,7 +177,6 @@ By default a `manual` endpoint is provided which can be used to manually trigger
 $ curl -H 'Authorization: Basic <base_64_encoded_login>' 'http://localhost:8080/manual?path=/path/to/file&hash=1234567890'
 ```
 
-
 ## To-do
 
 - [x] Add more triggers

assets/docs.css

@@ -0,0 +1,19 @@
+#trait-implementations,
+#trait-implementations-list,
+#synthetic-implementations,
+#synthetic-implementations-list,
+#blanket-implementations,
+#blanket-implementations-list,
+#implementations,
+#implementations-list,
+#traits,
+#traits-list,
+.trait-implementation,
+h3>[href="#trait-implementations"],
+.synthetic-implementation,
+h3>[href="#synthetic-implementations"],
+.blanket-implementation,
+h3>[href="#blanket-implementations"],
+h2#traits+ul {
+    display: none
+}

src/utils/conn.rs → src/db/conn.rs

@@ -5,10 +5,39 @@ use diesel::r2d2::{ConnectionManager, Pool, PooledConnection};
 use diesel::{Connection, ConnectionError, QueryResult, RunQueryDsl};
 use diesel::{SaveChangesDsl, SelectableHelper};
 
+/// Represents a connection to either a PostgreSQL or SQLite database.
 #[derive(diesel::MultiConnection)]
 pub enum AnyConnection {
+    /// A connection to a PostgreSQL database.
+    ///
+    /// This is used when the `database_url` is a PostgreSQL URL.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// postgres://user:password@localhost:5432/database
+    /// ```
     Postgresql(diesel::PgConnection),
     // Mysql(diesel::MysqlConnection),
+    /// A connection to a SQLite database.
+    ///
+    /// This is used when the `database_url` is a SQLite URL.
+    ///
+    /// Note: The directory where the database is stored will also be populated with a WAL file and a journal file.
+    ///
+    /// # Example
+    ///
+    /// ```bash
+    /// # Relative path
+    /// sqlite://database.db
+    /// sqlite://data/database.db
+    ///
+    /// # Absolute path
+    /// sqlite:///data/database.db
+    ///
+    /// # In-memory database
+    /// sqlite://:memory: # In-memory database
+    /// ```
     Sqlite(diesel::SqliteConnection),
 }
 
@@ -54,15 +83,18 @@ impl AnyConnection {
     }
 }
 
+#[doc(hidden)]
 pub type DbPool = Pool<ConnectionManager<AnyConnection>>;
 
+#[doc(hidden)]
 pub fn get_conn(
     pool: &Pool<ConnectionManager<AnyConnection>>,
 ) -> PooledConnection<ConnectionManager<AnyConnection>> {
     pool.get()
         .expect("Failed to get database connection from pool")
 }
 
+#[doc(hidden)]
 pub fn get_pool(database_url: String) -> anyhow::Result<Pool<ConnectionManager<AnyConnection>>> {
     let manager = ConnectionManager::<AnyConnection>::new(database_url);
 

src/db/migration.rs

@@ -1,10 +1,12 @@
 use diesel::r2d2::{ConnectionManager, PooledConnection};
 use diesel_migrations::{embed_migrations, EmbeddedMigrations, MigrationHarness};
 
-use crate::utils::conn::AnyConnection;
+use super::conn::AnyConnection;
 
+#[doc(hidden)]
 const MIGRATIONS: EmbeddedMigrations = embed_migrations!("migrations");
 
+#[doc(hidden)]
 pub fn run_db_migrations(conn: &mut PooledConnection<ConnectionManager<AnyConnection>>) {
     conn.run_pending_migrations(MIGRATIONS)
         .expect("Could not run migrations");

src/db/mod.rs

@@ -0,0 +1,11 @@
+/// Handles connections to multiple database engines
+pub mod conn;
+/// Handles database migrations
+///
+/// Note: All migrations are ran automatically when the application starts
+pub mod migration;
+/// Database models
+pub mod models;
+
+#[doc(hidden)]
+pub mod schema;

src/db/models.rs

@@ -3,6 +3,9 @@ use diesel::prelude::*;
 use serde::Serialize;
 use std::fmt::Display;
 
+use crate::utils::generate_uuid::generate_uuid;
+
+/// The status of a scan event being proccessed by [Targets](crate::service::targets).
 #[derive(Serialize)]
 pub enum ProcessStatus {
     Pending,
@@ -11,6 +14,9 @@ pub enum ProcessStatus {
     Failed,
 }
 
+/// Whether a file was found or not.
+///
+/// Note: only used if [opts.check_path](crate::utils::settings::Opts::check_path) is set.
 #[derive(Serialize)]
 pub enum FoundStatus {
     Found,
@@ -48,28 +54,45 @@ impl From<ProcessStatus> for String {
     }
 }
 
+/// Represents a scan event.
+///
+/// A scan event is created when a file is added by [Triggers](crate::service::triggers).
 #[derive(Queryable, Selectable, Serialize, Clone, Debug, AsChangeset, Identifiable)]
 #[diesel(table_name = crate::db::schema::scan_events)]
 pub struct ScanEvent {
+    /// The [uuid](crate::utils::generate_uuid::generate_uuid) of the scan event.
     pub id: String,
 
+    /// The name of the Trigger that created the scan event.
     pub event_source: String,
+    /// The time the scan event was created.
     pub event_timestamp: NaiveDateTime,
 
+    /// The rewritten path of the file.
     pub file_path: String,
+    /// Optional hash of the file.
     pub file_hash: Option<String>,
+    /// The status of the scan event being processed.
     pub process_status: String,
+    /// The status of the file being found.
     pub found_status: String,
 
+    /// The number of times the scan event has failed. Used for retries and is limited to [opts.max_retries](crate::utils::settings::Opts::max_retries).
     pub failed_times: i32,
+    /// The time the scan event will be retried.
     pub next_retry_at: Option<chrono::NaiveDateTime>,
 
+    /// The targets that have been hit by the scan event delimited by a comma.
     pub targets_hit: String,
 
+    /// The time the file was found.
     pub found_at: Option<chrono::NaiveDateTime>,
+    /// The time the scan event was processed.
     pub processed_at: Option<chrono::NaiveDateTime>,
 
+    /// The time the scan event was created.
     pub created_at: NaiveDateTime,
+    /// The time the scan event was updated.
     pub updated_at: NaiveDateTime,
 }
 
@@ -89,6 +112,7 @@ impl ScanEvent {
 
 #[derive(Insertable)]
 #[diesel(table_name = crate::db::schema::scan_events)]
+#[doc(hidden)]
 pub struct NewScanEvent {
     pub id: String,
     pub event_source: String,
@@ -99,11 +123,6 @@ pub struct NewScanEvent {
     pub found_status: String,
 }
 
-fn generate_uuid() -> String {
-    let uuid = uuid::Uuid::new_v4();
-    uuid.to_string()
-}
-
 impl Default for NewScanEvent {
     fn default() -> Self {
         Self {