No description
  • Go 51.3%
  • TypeScript 36.4%
  • CSS 7.9%
  • Go Template 2.1%
  • Dockerfile 1.6%
  • Other 0.7%
Find a file
jonasled e3e79ce28f
All checks were successful
ci / frontend-docker (push) Successful in 0s
ci / build-1 (push) Successful in 55s
ci / backend-test (push) Successful in 50s
ci / build (push) Successful in 3m15s
ci / backend-docker (push) Successful in 0s
ci / build-2 (push) Successful in 38s
ci / chart (push) Successful in 0s
revert 9d29ce3886
revert Merge pull request 'Update module github.com/swaggo/files to v2' (#44) from renovate/github.com-swaggo-files-2.x into master
2026-11-18 15:00:26 +00:00
.forgejo/workflows Port CI to Forgejo Actions 2026-11-18 10:41:50 +01:00
backend revert 9d29ce3886 2026-11-18 15:00:26 +00:00
deploy Update busybox Docker tag to v1.38 2026-10-27 00:04:30 +00:00
frontend Update cgr.dev/chainguard/nginx Docker digest to b05ccf9 2026-11-18 13:20:57 +00:00
.env.example Share rate limits across replicas and add IP exemptions 2026-10-25 12:59:48 +01:00
.gitignore Add Docker image, compose file, Makefile and README 2026-10-25 12:35:15 +01:00
.gitmodules Add TransceiverTool as submodule 2026-10-25 12:35:05 +01:00
docker-compose.yml Update postgres Docker tag to v18 2026-10-28 23:02:07 +00:00
Makefile Add Docker image, compose file, Makefile and README 2026-10-25 12:35:15 +01:00
README.md Share rate limits across replicas and add IP exemptions 2026-10-25 12:59:48 +01:00
renovate.json add renovate config 2026-10-25 12:21:30 +01:00

SFP Database

A database of SFP / SFP+ / SFP28 / QSFP / QSFP-DD transceiver EEPROM dumps. Visitors can browse, filter, download and view every field decoded from a dump. Anyone can submit a dump. An admin verifies submissions before they are listed.

  • Backend: Go, Gin, GORM. SQLite, MariaDB and PostgreSQL. No cgo.
  • Decoder: TransceiverTool (C++, SFF-8472 and SFF-8636), a git submodule in backend/third_party/transceivertool, run as a child process.
  • Frontend: React 19 with TypeScript and Vite. Light and dark theme follow the system setting.
  • API docs: Swagger UI at /swagger/index.html, linked from the header of the app.

Clone

git clone --recurse-submodules <repo-url>
# or, in an existing checkout:
git submodule update --init

Quick start (Docker)

cp .env.example .env          # set ADMIN_PASSWORD (and ideally ADMIN_TOKEN_SECRET)
docker compose up -d --build

Data lives in the sfp-data volume (SQLite file /app/data/sfp.db).

Development

Requirements: Go 1.27, Node 24, CMake 3.27+ and a C++17 compiler, plus the development packages for nlohmann-json, fmt 10 and CLI11 (the Dockerfile shows exact versions).

make tool                       # inits the submodule, builds bin/transceivertool
make test                       # Go tests (uses bin/transceivertool for the integration test)
cd backend && ADMIN_PASSWORD=dev TRANSCEIVER_TOOL=../bin/transceivertool \
  DB_NAME=../data/dev.db STATIC_DIR=../frontend/dist go run ./cmd/server     # API on :8080
cd frontend && npm install && npm run dev                                   # UI on :5173, proxies /api and /swagger

Regenerate the Swagger files after changing handler annotations (swag v1.16.x):

make swagger

Configuration

All settings are environment variables.

Variable Default Purpose
LISTEN_ADDR :8080 HTTP listen address
DB_DRIVER sqlite sqlite, mysql (alias mariadb), postgres (alias psql) or mssql
DB_NAME data/sfp.db Database name, or the file path for sqlite
DB_HOST – Server host (required for server databases)
DB_PORT per driver 3306 mysql, 5432 postgres, 1433 mssql
DB_USER – Database user (required for server databases)
DB_PASSWORD – Database password
DB_SSLMODE disable postgres sslmode
DB_TIMEZONE UTC postgres time zone (PostgreSQL rejects Local)
DB_ENCRYPT disable mssql encrypt
DB_TRUST_SERVER_CERTIFICATE true mssql TrustServerCertificate
DB_MAX_OPEN_CONNS 50 Connection pool limit (server databases)
DB_MAX_IDLE_CONNS 10 Idle connections kept (server databases)
DB_CONN_MAX_LIFETIME_MINUTES 5 Maximum lifetime of a pooled connection
TRANSCEIVER_TOOL transceivertool Path to the decoder binary
DECODER_TIMEOUT 5s Timeout per decode
DECODER_CONCURRENCY 4 Parallel decodes
STATIC_DIR frontend/dist Built frontend served for all non-API paths
ADMIN_USERNAME admin Admin user name
ADMIN_PASSWORD – Admin password (hashed at start-up). Required to enable admin login
ADMIN_PASSWORD_HASH – Alternative to ADMIN_PASSWORD: a bcrypt hash
ADMIN_TOKEN_SECRET random HMAC key for admin tokens. Set it, or sessions end on restart
ADMIN_SESSION_TTL 12h Admin token lifetime
UPLOAD_RATE_PER_HOUR 20 Public uploads and decode previews per client IP and hour (shared by all replicas)
LOGIN_RATE_PER_MINUTE 10 Admin login attempts per client IP and minute (shared by all replicas)
EXECUTE_MIGRATIONS true Run schema migrations at start-up. Set false on all but one replica if you want a single owner
TRUSTED_PROXIES – Comma separated CIDRs whose X-Forwarded-For is trusted (needed behind a reverse proxy)
LOG_LEVEL INFO ERROR, WARN, INFO or DEBUG
LOG_FOLDER – If set, also writes application.log with rotation to this folder

Database examples

sqlite:    DB_DRIVER=sqlite                      DB_NAME=data/sfp.db
mysql:     DB_DRIVER=mysql    DB_HOST=mariadb    DB_USER=sfp DB_PASSWORD=pw DB_NAME=sfp
postgres:  DB_DRIVER=postgres DB_HOST=postgres   DB_USER=sfp DB_PASSWORD=pw DB_NAME=sfp

Tables are created and migrated automatically with GORM AutoMigrate. docker-compose.yml has optional mariadb and postgres profiles (docker compose --profile postgres up -d). Then set DB_DRIVER, DB_HOST, DB_USER, DB_PASSWORD and DB_NAME in .env.

How submissions work

  1. A visitor uploads a dump: 128 bytes (SFF-8472 A0h page) or 256 bytes (SFF-8636, or A0h plus upper page). The upload can be a .bin file or hex text. Either form goes to POST /api/v1/submissions.
  2. The server validates the length, rejects all-zero or all-0xFF dumps, and checks the base checksum (SFF-8472 byte 63, SFF-8636 byte 191).
  3. A SHA-256 of the dump is computed. Identical dumps are rejected with 409 and the existing ID.
  4. TransceiverTool decodes the dump. The server extracts the searchable fields (form factor, speed, vendor, part number, connector, wavelength, reach, compliance codes, DDM) and stores the raw dump and the full decoded JSON.
  5. The entry is stored as pending. It is listed publicly only after an admin approves it in /admin.
  6. An admin can edit fields, re-parse the stored dump after a decoder update, approve, or delete (reject).

Public endpoints show only approved entries. Pending entries return 404.

API overview

Method Path Notes
GET /api/v1/modules Paginated list with filters: q, form_factor, speed, vendor, connector, standard, compliance, wavelength_min/max, reach_min_m, ddm, sort, page, page_size
GET /api/v1/modules/facets Distinct filter values with counts
GET /api/v1/modules/{id} Everything about one module, including hex dump and decoded JSON
GET /api/v1/modules/{id}/eeprom.bin Raw dump download
GET /api/v1/modules/{id}/decoded.json Decoded JSON download
GET /api/v1/modules/export.csv CSV of the filtered list
POST /api/v1/submissions Upload (rate limited)
POST /api/v1/decode Decode without storing (rate limited)
POST /api/v1/admin/login Returns a bearer token
GET/PATCH/DELETE /api/v1/admin/modules/{id} Admin view, edit, delete
POST /api/v1/admin/modules/{id}/approve Approve
POST /api/v1/admin/modules/{id}/reparse Decode the stored dump again
GET/POST /api/v1/admin/rate-exemptions List or add rate limit exemptions (IP or CIDR)
DELETE /api/v1/admin/rate-exemptions/{id} Remove an exemption

Full schemas and examples are in the Swagger UI.

Security notes

  • Admin login is rate limited per IP. Tokens are HMAC-signed and expire after ADMIN_SESSION_TTL. The frontend keeps the token in sessionStorage for the current tab only.
  • Uploads are validated and rate limited, and only approved entries are public. Notes and vendor strings are length limited. Vendor strings come from the dump and are shown as text, never as HTML.
  • The decoder runs with a timeout and a concurrency limit. It receives the dump on stdin, not as a file path.
  • Approved entries show their serial number on the detail page. Admins can edit or clear it in the edit dialog.

Known limits

  • Decoding follows the pinned TransceiverTool revision (submodule commit 811da32, v0.0.6). It covers SFF-8472 (SFP/SFP+/SFP28) and SFF-8636 (QSFP). CMIS modules (QSFP-DD, OSFP, SFP-DD) are decoded on a best-effort basis by the SFF-8636 path, so their speed and some fields can be wrong.
  • Speed is estimated from the nominal signalling rate and the lane count of the form factor. It is a label, not a guarantee.
  • There is one admin account, configured by environment variables.
  • Rate limits are fixed-window counters in the database, so all replicas share them. Each limit holds for the whole deployment. Admin tokens are stateless, so every replica needs the same ADMIN_TOKEN_SECRET.
  • Admins can exempt single IPs or CIDR ranges (Admin > Rate limit exemptions). An exempt client skips the limits on every replica. Replicas cache the list for 15 seconds, so a change made on another replica can take that long.
  • Replicas run schema migrations at start-up. A failed migration is retried, so replicas can start together.

Tests

make test          # Go unit tests and decoder integration test
make typecheck     # TypeScript

The EEPROM fixtures in backend/internal/eeprom/testdata are decoded with the pinned TransceiverTool (TransceiverTool decode --json-to-stdout). Run gen_fixtures.py to rebuild the QSFP binary. When the submodule is updated, regenerate the *.json fixtures and check the test expectations.

Licence

No licence has been chosen for this project yet. TransceiverTool, a submodule here, is MIT licensed (backend/third_party/transceivertool/LICENSE).