Skip to main content
Docs

Crate Reference

Comprehensive reference for the 19 heimdall-* crates (+ pegelonline) that make up the Heimdall backend.

Foundation Crates​

heimdall-config​

Location: crates/heimdall-config/

4-tier configuration loading for the Heimdall platform.

Key Exports: HeimdallConfig, DatabaseConfig, RedisConfig, ServerConfig, GeoIpConfig, SentryConfig, EmailConfig

Config Resolution Order (last wins):

  1. config/default.toml -- base defaults
  2. config/{APP_ENV}.toml -- environment-specific
  3. config/local.toml -- local overrides (git-ignored)
  4. HEIMDALL__* environment variables -- runtime overrides

Dependencies: config, serde, toml

heimdall-common​

Location: crates/heimdall-common/

Shared error types, pagination helpers, and response wrappers used across all crates.

Key Exports: ApiError, PaginationParams, PaginatedResponse, ApiResponse

Dependencies: actix-web, serde

heimdall-telemetry​

Location: crates/heimdall-telemetry/

Tracing subscriber initialization and Sentry error reporting setup.

Key Exports: init_tracing(), init_sentry()

Dependencies: tracing, tracing-subscriber, sentry

heimdall-api​

Location: crates/heimdall-api/

Actix-web infrastructure: CORS configuration, health check types, response helpers, and middleware traits.

Key Exports: configure_cors(), HealthResponse, response helpers

Dependencies: actix-web, actix-cors, heimdall-common

heimdall-proto​

Location: crates/heimdall-proto/

Shared Protobuf definitions for WebSocket communication between services (API, Discord bot, Twitch bot, YouTube bot).

Key Exports: WsEnvelope, WsMessageType, all message types (Subscribe, Pong, GpsUpdate, etc.)

Build: Proto code auto-generated at build time via build.rs from platform/proto/heimdall.proto

Dependencies: prost, prost-types

Data Layer Crates​

heimdall-db​

Location: crates/heimdall-db/

Database pool management, domain models, and SQL queries for PostgreSQL and TimescaleDB.

Key Exports: models::* (User, Role, Permission, ApiKey, Session, GpsData, OAuthClient, etc.), query functions, pool creation

Dependencies: sqlx, heimdall-config

heimdall-cache​

Location: crates/heimdall-cache/

Redis client wrapper for session caching, permission caching, rate limiting, and pub/sub.

Key Exports: RedisClient, cache methods for sessions, permissions, rate limits

Dependencies: deadpool-redis, redis, heimdall-config

heimdall-storage​

Location: crates/heimdall-storage/

S3-compatible storage client for file uploads and management.

Key Exports: StorageClient, sanitize_filename(), upload/download helpers

Dependencies: aws-sdk-s3, heimdall-config

Service Crates​

heimdall-audit​

Location: crates/heimdall-audit/

Shared audit event types and constants. No business logic, just type definitions.

Key Exports: AuditEventType, CreateAuditEvent, event type constants

Dependencies: serde

heimdall-audit-logger​

Location: crates/heimdall-audit-logger/

AuditLogger service that writes audit events to TimescaleDB with automatic GeoIP enrichment.

Key Exports: AuditLogger

Usage:

let audit_logger = AuditLogger::with_geoip(&tsdb_pool, &geoip_reader)
    .with_source_opt(source);
audit_logger.log_login(&user_id, ip, ua, Some("discord")).await;

Dependencies: heimdall-audit, heimdall-geoip, heimdall-db, sqlx

heimdall-auth​

Location: crates/heimdall-auth/

Authentication and authorization: JWT token creation/validation, OAuth 2.0 flows, RBAC permission checking, TOTP/2FA, and cryptographic utilities.

Key Exports: AuthContext, JwtManager, verify_totp(), hash_password(), check_permission()

Dependencies: jsonwebtoken, totp-rs, argon2, heimdall-db, heimdall-cache

heimdall-email​

Location: crates/heimdall-email/

Email service with Sailfish templates and rust-i18n for multi-language support.

Key Exports: EmailService, template structs for verification, password reset, account deletion, etc.

Template files: platform/api/templates/, platform/api/locales/

Dependencies: lettre, sailfish, rust-i18n, heimdall-config

heimdall-geoip​

Location: crates/heimdall-geoip/

MaxMind GeoLite2 IP-to-location lookup with privacy exclusions support.

Key Exports: GeoIpReader, GeoIpLocation

Dependencies: maxminddb, heimdall-config

heimdall-integrations​

Location: crates/heimdall-integrations/

Streaming platform OAuth service: Twitch, YouTube, Kick, Trovo token management and API interaction.

Key Exports: IntegrationService, platform-specific OAuth clients

Dependencies: reqwest, heimdall-db, heimdall-config

heimdall-scheduler​

Location: crates/heimdall-scheduler/

Background jobs and scheduled tasks (account deletion processor, token refresh, data cleanup).

Key Exports: Scheduler, job implementations

Dependencies: tokio-cron-scheduler, heimdall-db, heimdall-email

API Layer Crates​

heimdall-rest​

Location: crates/heimdall-rest/

REST handlers, route configuration, OAuth HTTP endpoints, and middleware (auth, rate limiting, 2FA).

Key Modules:

  • handlers/ -- Request handlers for all REST endpoints
  • routes/ -- Actix-web route configuration (configure_routes(), configure_public_routes(), etc.)
  • middleware/ -- Auth middleware, rate limiting, 2FA enforcement
  • oauth/ -- OAuth 2.0 endpoint handlers

Dependencies: actix-web, heimdall-auth, heimdall-db, heimdall-cache, heimdall-audit-logger

heimdall-graphql​

Location: crates/heimdall-graphql/

GraphQL types, resolvers, and schema definition using async-graphql.

Key Exports: build_schema(), query/mutation root types, GraphQL type structs (GqlUser, GqlGpsData, etc.)

Dependencies: async-graphql, heimdall-db, heimdall-auth, heimdall-cache, heimdall-audit-logger

heimdall-websocket​

Location: crates/heimdall-websocket/

WebSocket server implementation: session management, channel pub/sub, message routing, and protocol detection (JSON/Protobuf).

Key Exports: WsServer, WsSession, route handler

Key Module: route -- Actix-web WebSocket route handler

Dependencies: actix-web, actix-ws, heimdall-proto, heimdall-db, heimdall-cache, heimdall-auth

Crate Dependency Graph (Simplified)​

heimdall-config ──────────────────────────────────────┐
heimdall-common ──────────────────────────────────────┤
heimdall-telemetry ───────────────────────────────────┤
heimdall-proto ───────────────────────────────────────┤ Foundation
heimdall-audit ───────────────────────────────────────┤
heimdall-api ─────────────────────────────────────────┘
                         │
heimdall-db ─────────────┤
heimdall-cache ──────────┤ Data Layer
heimdall-geoip ──────────┤
heimdall-storage ────────┘
                         │
heimdall-auth ───────────┤
heimdall-audit-logger ───┤ Services
heimdall-email ──────────┤
heimdall-integrations ───┤
heimdall-scheduler ──────┘
                         │
heimdall-rest ───────────┤
heimdall-graphql ────────┤ API Layer
heimdall-websocket ──────┘
                         │
platform/api ────────────  Binary (glue)

External Data Crates​

heimdall-pegelonline​

Client for the German PegelOnline API (water level gauging stations). Fetches nearest stations, current measurements, and historical data.

Dependencies: reqwest, serde, heimdall-config

Next Steps​