Overview

Relevant source files

• Cargo.toml
• README.md

This page describes the purpose, audience, and high-level operation of deadlock-api-ingest. It covers what the application does, the data flow from the local Steam cache to the remote API, and a map of the major subsystems. For installation instructions, see Quick Start. For internal module-level design, see Core Architecture.

---

What It Is

deadlock-api-ingest is a lightweight background process that runs on a Steam user's machine. It watches the local Steam HTTP cache for Deadlock replay URL fragments, extracts match identifiers (match IDs and salts) from those cached files, and submits them via HTTP POST to api.deadlock-api.com. The API then uses those identifiers to retrieve full replay data directly from Valve's CDN.

The application never reads full replay data, never contacts Valve directly, and never modifies any files. Its only job is to extract small URL metadata that Steam has already cached locally, then forward it.

Key properties:

Property	Detail
Language	Rust (edition 2024, toolchain pinned to 1.83)
Runtime model	Background process / system service
Files read	Steam appcache/httpcache/ (.meta.bz2, .dem.bz2)
Files written	Log files, fetched-salts.jsonl (ingestion record)
External calls	api.deadlock-api.com POST, optionally statlocker.gg
Privilege level	Standard user — no elevation required

Sources: README.md1-13 Cargo.toml1-7

---

Why It Exists

Valve does not expose a public API for Deadlock match replay data. However, the Steam client caches replay URL references locally as part of its normal HTTP caching layer. These cached fragments contain the match ID and a cryptographic salt needed to authenticate replay downloads. By collecting these identifiers from volunteer users' machines, the Deadlock API can build a comprehensive match database that would otherwise be inaccessible.

Sources: README.md1-13

---

Who It Is For

• End users who play Deadlock and want to contribute match data to the community database. They install the tool and it runs silently in the background.
• Developers and contributors who want to understand or extend the ingestion pipeline. See Development Guide.
• Self-hosters who run it as a Docker container or NixOS service. See Docker Installation and NixOS Installation.

---

High-Level Data Flow

Diagram: End-to-End Data Flow

Sources: README.md6-8

---

System Context

Diagram: System Boundary and External Interactions

Sources: README.md6-13 Cargo.toml9-29

---

Module Structure

The application is a single Rust binary composed of seven source modules. main.rs is the entry point and orchestrator; all other modules are called from it.

Diagram: Rust Module Dependency Graph

Sources: Cargo.toml1-30

---

Core Concepts

Steam HTTP Cache

When the Steam client handles Deadlock replay requests, it caches URL references in appcache/httpcache/. Files with .meta.bz2 and .dem.bz2 extensions contain embedded replay URL strings of the form:

http://replayNNN.valve.net/570/<match_id>/<salt>.dem.bz2

The application extracts these URLs using a byte-scan algorithm (extract_replay_url in src/utils.rs) that searches for a known byte sequence and validates the Deadlock app ID (570).

Match IDs and Salts

A Salts struct (defined in src/utils.rs) holds the parsed fields from one replay URL: the match ID, a metadata_salt, and a replay_salt. These are the only values submitted to the API. No player data, no game content, and no personal information is included.

Deduplication

The INGESTION_CACHE (an OnceLock<RwLock<HashMap<u64,(bool,bool)>>> in src/ingestion_cache.rs) ensures each match ID is submitted at most once per run. It is backed by fetched-salts.jsonl on disk for persistence across restarts.

Continuous Watching

After an initial bulk scan of the cache directory (initial_cache_dir_ingest), the application switches to an event-driven watch mode (watch_cache_dir) using the notify crate. New cache files are processed as they appear, so matches are submitted shortly after a game ends.

For detailed treatment of each concept, see Core Architecture.

---

Installation Summary

Four installation paths are supported. See Quick Start for the minimal commands, or the sub-pages for full details.

Platform	Method	Auto-start mechanism	Detail page
Windows	PowerShell installer script	Windows Scheduled Task	Windows Installation
Linux	Bash installer script	systemd user service	Linux Installation
Docker	docker run with volume mount	--restart unless-stopped	Docker Installation
NixOS	Flake module or nix run	systemd system service	NixOS Installation

Sources: README.md19-144

---

Privacy Model

• Reads: Steam cache directory only (.meta.bz2, .dem.bz2 files)
• Writes: Log directory and fetched-salts.jsonl (local only)
• Transmits: Match ID + salt pairs only — no player names, no game content, no account data
• File access: Read-only on the Steam cache; no files are ever modified or deleted
• Transport: All outbound HTTP uses TLS (via ureq with rustls)

For the full security and privacy breakdown, see Privacy & Security.

Sources: README.md202-209 Cargo.toml10