snowstorm
    Preparing search index...

    snowstorm

    Snowstorm - App

    A new era for Snowstorm; the future of internet freedom.

    See: Primary Snowstorm App Documentation

    Platform Build SDK E2E Network CICD Released Beta Stability Confidence Level Launch
    MacOS ✅ ✅ ✅ ✅ ✅ ✅ 70% ⚠️
    iOS ✅ ✅ ✅ ✅ ✅ ✅ 70% ⚠️
    Android ✅ ✅ ✅ ✅ ✅ ✅ 50% ⚠️
    Windows ✅ ✅ ✅ ✅ ✅ ✅ 30% ⚠️

    On mac, make sure to open Xcode and login with your Snowstorm Apple ID. It will be later used for automatic code signing.

    • Fresh Clone: git clone git@github.com:project-snowstorm/snowstorm
    • yarn install
    • TLDR: yarn macos:dev, yarn ios, yarn android
    • Fix problems / dependencies: yarn cache clean followed by yarn install. Sometimes cargo build can help.
    • Lint: yarn lint (and more - see package.json)

    Screenshots 2025-01-17

    There are two ways to build / test: directly from terminal, or via Xcode.

    Preparation: yarn tauri ios init - Generates an Xcode Project for you in src/tauri/gen/apple. Make sure to open Xcode and login with your Snowstorm Apple ID. It will be later used for automatic code signing.

    Via Xcode: yarn ios CLI only & deploy to physical phone: yarn tauri ios dev "iphone hostname"

    TODO: check if still relevant, latest changes have automatic signing in dev by defauilt, so xcode is only needed to log in with the snowstorm apple ID.

    • Under the hood, yarn ios runs yarn tauri ios dev --open, which opens the Xcode project.
    • ⚠️ It's helpful to do this at least once after initialization. You will need to set your Apple Developer info, potentially recognize your physical phone as a device, or you may get errors.
    • Once setup, you can click RUN from Xcode to deploy dev environment to an iOS Simulator, or your actual iPhone.

    There's a lot of black magic to get Swift, Testflight all playing nicely, but it works.

    See: Snowstorm iOS Guide

    You can also run android on emulator, or on a physical device if it's plugged in. Make sure adb and other pre-requisites exist.

    See: Snowstorm Android Guide

    TLDR; yarn android

    (Under the hood, this runs yarn tauri android dev -- if there are issues, kill the emulator and restart it)

    This is the first platform / native dev platform that we started with.

    To run the app with HMR enabled:

    yarn macos:dev

    See: Snowstorm App - Main Guide

    * After introducing Network Extension for our VPN functionality we had to move away from tauri's built-in dev command in favor of a custom setup.

    In the custom setup there is an actual Xcode project under src/apple/macos_app which is used both in dev and build modes. A dedicated Xcode project helps us with automatic signing of the main app & the network extension, which in turn let us run it on our dev devices. NOTE: This is not compatible with TestFlight Catalyst running the iOS version of Snowstorm on your Mac machine concurrently: please uninstall the TestFlight version first.

    On mac it's possible to open system extension settings via cli:

    open "x-apple.systempreferences:com.apple.ExtensionsPreferences?extensionPointIdentifier=com.apple.system_extension.network_extension.extension-point"

    yarn dev (From a Windows machine)

    You may also need:

    • brew install protobuf

    DOCUMENTATION SYSTEMS IN PROGRESS

    yarn docs - generate all documentation locally.

    • yarn docs:sdk
    • yarn docs:ts

    For now, the docs/ folder is mostly git-ignored other than the index, because we don't want to bloat the repo, and we don't need it exposed as a public github page, etc. But you can generate the docs locally and take a look.

    We can also push the docs to our SSO-protected Cloudflare Pages, at docs.snowstorm.tech - by using cloudflare's wrangler CLI. This is automated with a script at docs/upload.sh and can also be called with yarn docs:upload.

    Please continue to improve in-code documentation!

    TODO: These can be processed via CI at some point and sent to a dedicated website elsewhere.

    Developer Experience (DX) is extremely important for our productivity and general well-being while executing on things. Defending global internet freedom is a very difficult thing to do. It requires excellence on all levels, and internal trust and reliability in the quality of the code, as a prerequisite for other people, the external users, to also have that trust in us.

    But as in any software project, little problems and frictions - technical debt - can grow into large scary monsters that create regressions, problems, delays. We must pre-empt all that. In addition to good documentation so we know what's going on, please also make use of clean code habits & organization:

    • Well defined interface & scopes
    • DRY (Don't repeat yourself)
    • Concise but descriptive naming
    • General style consistency (see lint below)
    • Don't write fragile code, fragile tests, or break things / introduce regressions.
    • Absolutely NO AI SLOP CODE.
    • etc etc...

    One of the fun things we have implemented are husky pre-commit hooks within the repo.

    Each commit you make will run linters and local tests on all the code before the commit will be accepted. Husky is activated upon fresh clone, but you can double check that by running yarn husky.

    🚨 We are STILL in dire need of more automated tests, integration tests, unit tests, E2E tests, stress tests, etc.

    You can run tests manually:

    • yarn test - Runs vitest based tests primarily to test the front-end side. You can also run only specific tests.
    • To run a specific test, do yarn test -t "name / regex of test".
    • TODO: Also should test all rust related things.
    • yarn smoke - runs a simple smoke test on the osx desktop build to make sure it at least doesn't just crash. This is being inserted into CI as well.

    Please help make this situation better! Until we have comprehensive E2E / integration tests, it's still very important to manually QA the app especially when working on the frontend, to prevent breakages.

    See: https://www.notion.so/Manual-QA-Testing-Checklist-294582318d1180feb5d2f5643e27ac1e

    • We are using cargo clippy wrapped in the yarn lint command for rust-related linting. The config for that is handled in src-tauri/clippy.toml. Clippy has to be in the tauri subdirectory because it's required as a cargo subcommand, and cargo is only directly accessible from that directory.
    • In emergencies, you can git commit with the --no-verify to skip the precommit hook.

    In emergencies, if you truly need to override the pre-commit hook and skip some problems that are not able to be solved, you can commit with --no-verify. But do not make this a habit as here be dragons.

    There's a tiny command we can run to have a headless SDK running which automatically creates a share. Feel free to use the key from test@snowstorm.net or some other personal test user. The bin spits out a n.sig thingy inside the logs.

    cargo run --example shared_exit  -- --license SOME-LICENSE-KEY --seed 42

    With a few opinionated defaults, this can have smaller binary size than stock Tauri templates. These can be revisited if needed:

    • panic = "abort" The compiler will abort the program immediately when a panic occurs in production. Without performing any cleanup. Code will execute faster, the tradeoff is you won't get as much information about the panic when it occurs.

    • codegen-units = 1 Explicitly tells the compiler to use only one code generation unit during compilation. Code generation units (CGUs) represent individual units of code that the compiler processes independently.

    Reducing CGUs to a minimum will potentially reduce memory consumption and leads to faster compilation time. This setting hinders parallelization, so it's worth to benchmark if it becomes a problem in CICD.

    • lto = true Link Time Optimization (lto) enables the compiler to make more aggressive optimizations than it can do at the individual file level, resulting in potentially significant performance improvements in the final executable. However, enabling LTO may increase compilation times and require more memory during the linking phase, as the compiler needs to analyze and optimize a larger amount of code.

    • opt-level = "s"

    Specifying the optimization level to be "size-optimized." This option instructs the compiler to prioritize reducing the size of the generated code while still aiming for reasonable performance.

    Using "s" is a balanced optimization. Some apps may find faster compilation times with opt-level="z", though this may bring slower runtime performance as a tradeoff.

    • strip = true

    Stripping symbols from generated code is generally recommended for release builds where binary size is a concern, and debuggability is less critical. It helps produce leaner binaries, which can be beneficial for deployment, distribution, or running in resource-constrained environments. Additionally, it can slightly enhance security because it makes the binaries harder to analyze.

    Follow our project online:

    Winter is Coming.

    Settings

    Member Visibility

    On This Page

    Snowstorm - App