grpc_server

Important

The canonical repository for this project lives on Forgejo: https://code.bhk-itsolutions.com/homeiot/grpc_server.git. This GitHub repository is only a mirror and is not the primary git remote.

gRPC / gRPC-Web server for the Home IoT project. Exposes installation services (web client, bridge) and event broadcasting.

Prerequisites

• Rust (edition 2021, stable toolchain)
• Forgejo registry — This crate depends on db_handler, which is published on a private Forgejo Cargo registry. You need access to that registry to build and run.
• Configuration file (see below)

Forgejo registry setup

The registry is declared in .cargo/config.toml (sparse index URL). To authenticate:

1. Obtain a token with read access to the Forgejo package registry (e.g. from your Forgejo instance: User → Settings → Access Tokens, or from the project/package permissions).
2. Log in to the registry:

   cargo login --registry forgejo <YOUR_TOKEN>
   

   Alternatively, set the token in your environment so it is not stored in the Cargo credentials file:

   export CARGO_REGISTRIES_FORGEJO_TOKEN="<YOUR_TOKEN>"
   

3. Run cargo build or cargo test as usual; Cargo will use the token to fetch db_handler from the registry.

Without valid credentials, cargo build will fail when resolving the db_handler dependency.

Configuration

Configuration is read by the db_handler crate via the CONFIG_FILE environment variable (path to a JSON file).

• Copy the example file:
  cp config.example.json config.json
  (or create a config file at the path of your choice.)

• Adjust the fields (SQLite database URL, InfluxDB, etc.) in that file. The structure is defined by db_handler (e.g. primary_db_url, history_db_url, history_db_org, history_db_token).

• Run the server or tests with CONFIG_FILE set:

  export CONFIG_FILE=/path/to/config.json
  ./scripts/run.sh
  

A secret-free example is provided in config.example.json.

Server bind (loopback-only plaintext)

The plaintext gRPC listener is loopback-only by design: it binds to 127.0.0.1 (or ::1) and refuses to start on any non-loopback host with an explicit error. Direct exposure of this process to a LAN or the internet is impossible by construction; transport encryption is the responsibility of an identified on-host TLS terminator (nginx) that proxies to the loopback port. frontTs and bridge therefore connect via https://<host> through nginx — never directly to this process.

• GRPC_PORT — listening port (default 50051).
• GRPC_HOST — bind host; only 127.0.0.1 (default) or ::1 are accepted, any other value aborts startup.

Build

cargo build
# Release
cargo build --release
# or
./scripts/build.sh

Tests

All tests (unit, integration, doc-tests) are run with:

./scripts/tests.sh

The script uses CONFIG_FILE=config_test.json (relative to the project root). Create it from the example if needed: cp config.example.json config_test.json, then run the script. Or set CONFIG_FILE to another path and run cargo test (or the script) as needed.

For integration test details (timeouts, concurrency, CORS, load), see tests/README.md.

Running

export CONFIG_FILE=/path/to/config.json
./scripts/run.sh
# or for development
./scripts/runDev.sh

Project structure

• src/ — Source code: main.rs, lib (shared modules)
  • broadcaster/ — Event broadcasting
  • common/ — Errors, response channels, shared types
  • install/ — Installation: web_client (gRPC-Web), bridge
• proto/ — .proto files (gRPC definitions)
• tests/ — Integration tests and test documentation
• scripts/ — Build, test, run, and deploy scripts

License

See LICENSE (Personal Use Only — Non-Commercial).