3.7 KiB
extract
Document text extraction service. Drop-in replacement for Huly's rekoni:
takes a file (or URL), returns the plain text plus light metadata. Pure
Go, distroless, IAM-authenticated, no Python sidecars.
Image: ghcr.io/hanzoai/extract
Port: 4004
Supported formats
Format detection is by magic bytes, not filename. Filenames are advisory only.
| Format | Backend |
|---|---|
github.com/ledongthuc/pdf (MIT, pure Go) |
|
| DOCX | native ZIP + XML walk (word/document.xml) |
| XLSX | native ZIP + XML walk (sharedStrings + sheets) |
| PPTX | native ZIP + XML walk (ppt/slides/slide*.xml) |
| HTML | golang.org/x/net/html, scripts/styles dropped |
| RTF | small native parser, ignores font/style/info groups |
| Markdown | pass-through |
| Plain text | pass-through |
| Images | rejected with HTTP 415 in v0.1 |
API
All routes are under /v1/. Auth is required on extraction endpoints: bearer
JWT issued by Hanzo IAM, verified against the IAM JWKS (IAM_JWKS_URL,
default https://hanzo.id/v1/iam/.well-known/jwks). RS256 and RS512 are accepted;
HS* and none are rejected.
GET /v1/health
{ "status": "ok", "version": "v0.1.0" }
POST /v1/extract
Multipart upload, single field file. Max upload 25 MB (streamed —
the service does not buffer the whole form in memory).
curl -sf \
-H "Authorization: Bearer $HANZO_TOKEN" \
-F "[email protected]" \
https://api.hanzo.ai/v1/extract
Response:
{
"text": "Hanzo extract pdf fixture.\n",
"metadata": { "pages": 1 },
"format": "pdf",
"language": "en"
}
POST /v1/extract/url
curl -sf \
-H "Authorization: Bearer $HANZO_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/cv.docx"}' \
https://api.hanzo.ai/v1/extract/url
Only http:// and https:// schemes are accepted. The remote fetch is bounded
by FetchTimeout (20s) and the same 25 MB cap.
Errors
| Code | Meaning |
|---|---|
| 400 | malformed request (multipart, JSON, missing file) |
| 401 | missing / expired / unverifiable bearer |
| 403 | URL-fetch allowlist refused the target |
| 413 | upload (or remote payload) over 25 MB |
| 415 | format unsupported (e.g. images in v0.1) |
| 422 | extractor saw a recognized format but failed to parse |
| 502 | remote URL fetch failed |
All error responses are {"error":"..."} JSON.
Configuration
| Env | Default |
|---|---|
LISTEN_ADDR |
:4004 |
IAM_JWKS_URL |
https://hanzo.id/v1/iam/.well-known/jwks |
Build & run
make test # go test ./... with -race -cover
make build # static linux/amd64 binary
make run # local dev on :4004
make docker # ghcr.io/hanzoai/extract:dev
Deploy
CI builds amd64 image on tag push via shared hanzoai/.github workflow.
arm64 paused per global LLM.md (DOKS has no arm64 droplets as of 2026-04-27).
Kubernetes drop-in:
containers:
- name: extract
image: ghcr.io/hanzoai/extract:v0.1.0
ports: [{containerPort: 4004}]
env:
- name: IAM_JWKS_URL
value: https://hanzo.id/v1/iam/.well-known/jwks
readinessProbe:
httpGet: { path: /v1/health, port: 4004 }
resources:
requests: { cpu: 100m, memory: 128Mi }
limits: { cpu: 1, memory: 512Mi }
Notes
- No filename trust. Always magic-byte detection.
- No CGo, no shelled binaries. Distroless static base.
- Tests build OOXML and PDF fixtures at runtime — see
pkg/extract/fixtures_test.go. - Image OCR will land in a later version; v0.1 returns HTTP 415 with a clear message.
Licensed under MIT OR Apache-2.0, per HIP-0137.