- Go 51.3%
- TypeScript 36.4%
- CSS 7.9%
- Go Template 2.1%
- Dockerfile 1.6%
- Other 0.7%
|
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 Merge pull request 'Update module github.com/swaggo/files to v2' (#44) from renovate/github.com-swaggo-files-2.x into master |
||
|---|---|---|
| .forgejo/workflows | ||
| backend | ||
| deploy | ||
| frontend | ||
| .env.example | ||
| .gitignore | ||
| .gitmodules | ||
| docker-compose.yml | ||
| Makefile | ||
| README.md | ||
| renovate.json | ||
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
- App: http://localhost:8080
- API docs: http://localhost:8080/swagger/index.html
- Admin: http://localhost:8080/admin (user
ADMIN_USERNAME, defaultadmin)
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
- 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
.binfile or hex text. Either form goes toPOST /api/v1/submissions. - 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).
- A SHA-256 of the dump is computed. Identical dumps are rejected with
409and the existing ID. - 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.
- The entry is stored as
pending. It is listed publicly only after an admin approves it in/admin. - 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 insessionStoragefor 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).