projectmycelium/README.md

Project Mycelium

Installation

Prerequisites

• Rust and Cargo (latest stable version)
• Git

Setup

1. Clone the repository:

   git clone https://git.ourworld.tf/tfgrid_research/projectmycelium
   cd projectmycelium
   

2. Build the project:

   cargo build
   

3. Run the application:

   cargo run
   

To run with a different port:

cargo run -- --port 9998

4. Open your browser and navigate to http://localhost:9999

Architecture

Project Mycelium is a Rust web app built on Actix Web.

• Backend (Rust/Actix Web):
  • Routes: src/routes/mod.rs
  • Controllers: src/controllers/
  • Middleware: src/middleware/
  • Config: src/config/
  • Library crate: src/lib.rs; Binary: src/main.rs
• Views and Static Assets:
  • Templates (Tera): src/views/
  • Frontend JS: src/static/js/ (CSP-compliant; no inline JS)
• API Contract:
  • Responses follow a ResponseBuilder JSON envelope. Frontend unwraps with:

    const result = await response.json();
    const data = result.data || result;
    

  • Display rules: render "No limit" for null/undefined numeric limits; prefer server-formatted amounts.

Marketplace Overview

• Roles & Areas
  • End user, Farmer, Application Provider, Service Provider dashboards: /dashboard/{user|farmer|application-provider|service-provider} (see DashboardController in src/controllers/dashboard.rs).
  • Public catalogue: /marketplace, /products, /products/{id}, /cart, /checkout.
• Core Concepts
  • Products (apps, services, compute). Orders and cart lifecycle.
  • Slices (compute resources) on the ThreeFold Grid, publicly listed at /marketplace/compute.
  • Credits wallet for balance, transactions, quick top-up, and auto top-up.
• Primary Flows
  • Browse products: /products, details at /products/{id}; APIs under /api/products*.
  • Cart & checkout: /cart, /checkout; APIs under /api/cart* and /api/orders*.
  • Slice rental: forms at /marketplace/slice/rent*; APIs include /api/products/{id}/rent and /api/marketplace/rent-slice.
  • Wallet & credits: dashboard page /dashboard/wallet; APIs under /api/wallet/* (balance, transactions, instant purchase, quick top-up, auto top-up).
  • Settings & SSH keys: /dashboard/settings; APIs under /api/dashboard/settings/* and /api/dashboard/ssh-keys*.

Security & CSP

• Security headers (via SecurityHeaders in src/middleware/mod.rs, enabled in src/main.rs):
  • X-Content-Type-Options: nosniff
  • X-Frame-Options: DENY
  • X-XSS-Protection: 1; mode=block
• CSP practice:
  • No inline JavaScript in templates; all JS under src/static/js/.
  • Templates (Tera) should hydrate data via JSON blocks, keeping CSP-friendly structure.
  • Note: A Content-Security-Policy response header is not set yet. Recommended policy (production):

    Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; frame-ancestors 'none'
    

    Adjust as needed for external assets or APIs.

Authentication & Sessions

• Auth flows (src/routes/mod.rs):
  • Gitea OAuth when GITEA_CLIENT_ID is set (see src/config/oauth.rs).
  • Username/password login otherwise (src/controllers/auth.rs).
• Password hashing: bcrypt for stored password hashes.
• Sessions (actix-session):
  • Cookie store with HttpOnly and SameSite=Lax, TTL 2h, name project_mycelium_session.
  • cookie_secure=false in dev; enable true behind HTTPS in production.
• JWT (auth_token cookie):
  • Set as HttpOnly; secure=false in dev. Enable secure=true in production.
  • Dashboard and protected scopes are wrapped by JwtAuth middleware.

Repository Layout

• docs/dev/ — Design, guides, and methodologies
  • Roadmap and UX contracts: docs/dev/design/projectmycelium-roadmap.md
• docs/ops/ — Ops notes and runbooks
• config/zinit/ — Service definitions (dev/prod)
• scripts/ — Utilities and deployment helpers
• src/ — Application source (routes, controllers, views, static assets)
• tests/frontend_ux/ — UX test suite (feature-gated)
• user_data/ — Test fixtures and persistent data used by UX tests

Documentation

Key design and UX contract documentation lives in:

• docs/dev/design/projectmycelium-roadmap.md
  • Canonical UX contracts (e.g., SSH Keys, Settings, Auto Top-Up)
  • Proven debugging methodology and marketplace-wide audit plan

Testing

UX tests are written in Rust using WebDriver clients (thirtyfour, fantoccini) and run under the ux_testing feature flag.

• Run all UX tests:

  cargo test --features ux_testing -- --nocapture
  

• Individual suites (from Cargo.toml):
  • public_access_ux, authentication_ux, purchase_cart_ux, credits_wallet_ux
  • marketplace_categories_ux, provider_dashboards_ux, settings_management_ux, ssh_key_frontend_ux
• Requirements: Ensure a compatible WebDriver (e.g., ChromeDriver/GeckoDriver) is available on PATH.
• Pattern: Tests follow a per-step runner with persistent fixtures under user_data/ for deterministic results.

Develop

see https://git.ourworld.tf/herocode/rweb_starterkit is the web starter kit

Usage

Basic Usage

Once the application is running, you can access it through your web browser at http://localhost:9999. The default configuration provides:

• Home page at /
• About page at /about
• Contact page at /contact
• Login page at /login
• Registration page at /register

Configuration

see https://git.ourworld.tf/herocode/rweb_starterkit is the web starter kit