How fingerprintjs/fingerprint-pro-fastly-compute-proxy-integration works
Project type and purpose
• This is a serverless edge-compute proxy integration for Fingerprint Pro, built on Fastly Compute.
• Its job is to sit in front of Fingerprint’s identification API and JavaScript agent CDN, forwarding requests from client browsers through your Fastly network, using Fastly Config and Secret stores for runtime parameters and credentials.
File structure
• Top-level:
• src/ – TypeScript entry points and handler implementations
• plugins/ – extension points (e.g., saveToKVStore)
• scripts/ – CLI and CI helpers for service lifecycle (createService, deployPackage, mock tests)
• __mocks__/ – test doubles for Fastly runtime bindings
• test/ – unit and integration tests for handlers and utilities
• Configuration files for linting, formatting, deployment (babel.config.js, build.ts, fastly.toml, GitHub workflows).
• The src/handlers folder holds three core routes:
• handleDownloadScript.ts – serves the Fingerprint JS agent
• handleIngressAPI.ts – forwards identify (GET_RESULT_PATH) requests
• handleStatusPage.ts – health/status endpoint
• src/utils contains common HTTP helpers, encryption/unsealing logic, proxy headers, plugin registration, etc.
README for additional insights
• Describes Fastly Config store keys (AGENT_SCRIPT_DOWNLOAD_PATH, GET_RESULT_PATH, OPEN_CLIENT_RESPONSE_PLUGINS_ENABLED).
• Describes Fastly Secret store key (PROXY_SECRET).
• Emphasizes two distinct proxy flows: one for the JS agent download and one for identification requests.
Main components and interactions
a. Client Browser (Customer Website)
– Runs FingerprintJS agent configured to point at your Fastly domain + AGENT_SCRIPT_DOWNLOAD_PATH/GET_RESULT_PATH.
b. Fastly CDN / Edge Compute Service
– DNS entry (e.g., metrics.yourwebsite.com)
– Compute edge runtime hosting the compiled package (handler.ts + plugins)
– Config Store (AGENT_SCRIPT_DOWNLOAD_PATH, GET_RESULT_PATH, plugin flags)
– Secret Store (PROXY_SECRET)
c. Fingerprint Pro API (External Service)
– Identification endpoint behind Fingerprint’s CDN/API
– JavaScript agent CDN fallback
d. (Optional) KV Store Plugin
– If enabled, used by saveToKVStore plugin to cache or log requests at edge
e. CI/CD / GitHub Actions (build, test, release)
– Build pipeline compiles TS, runs jest, packages fingerprint-proxy-integration.tar.gz, and publishes releases
Relationships and data flows
1) Browser requests https://metrics.yourwebsite.com/AGENT_SCRIPT_DOWNLOAD_PATH → Fastly Compute → src/handlers/handleDownloadScript → fetch JS agent from Fingerprint CDN or local cache → return to browser.
2) Browser calls https://metrics.yourwebsite.com/GET_RESULT_PATH?region=us → Fastly Compute → src/handlers/handleIngressAPI → authenticate with PROXY_SECRET → forward to Fingerprint Pro Identification API → receive JSON identity → apply any open-client-response plugins → return to browser.
3) Health checks to / (or /status) → src/handlers/handleStatusPage → return 200 OK.
Architectural patterns and highlights
• Edge-compute proxy pattern: small handlers orchestrating HTTP forwarding, authentication, and response transformation.
• Plugin registry: src/utils/registerPlugin dynamically hooks into request/response lifecycle.
• Configuration via Fastly Config + Secret stores keeps code generic and zero-config at compile time.
• TypeScript modularity: clear separation of handlers, utilities, and plugins.
• Fastly Compute@Edge (Rust-powered edge environment)
• TypeScript / Babel / build.ts → compiled to a WebAssembly or JS package
• Fastly Config Store & Secret Store
• Fingerprint Pro REST API & JS agent CDN
• GitHub Actions for CI/CD
• Jest for unit tests, husky & commitlint for repo quality