Barcode Hub

Barcode Hub is a Python service for barcode recognition over HTTP and MCP. The recognition backend is zxing-cpp.

The API response body is intentionally minimal:

{
  "barcodes": [
    {
      "text": "4607084351323",
      "data": "NDYwNzA4NDM1MTMyMw==",
      "type": "EAN13",
      "valid": "yes",
      "coords": {
        "top_left": {"x": 12, "y": 34},
        "top_right": {"x": 212, "y": 34},
        "bottom_right": {"x": 212, "y": 88},
        "bottom_left": {"x": 12, "y": 88}
      }
    }
  ]
}

Build identity is emitted at runtime as an HTTP Server header on every response, but it is not part of the OpenAPI or MCP contracts.

Endpoints

Single service port, default 8080:

• GET / shows a small HTML server index with build info and resource links
• GET /decode?url=...&types=EAN13,UPCA&return_errors=true
• POST /decode with exactly one multipart/form-data image file
• PUT /decode with raw image bytes and an allowed image/* Content-Type
• GET /health checks that zxingcpp is importable and exposes the required API
• GET /metrics exposes Prometheus metrics
• /mcp when MCP is enabled
• /docs, /redoc, /openapi.json

types is optional. When omitted, decode.default_formats is used. Values are canonical Barcode Hub type IDs, with common aliases such as EAN-13, UPC-A, and QR Code accepted on input. Requested types must be inside decode.allowed_formats.

return_errors is optional on all /decode methods. When omitted, decode.return_errors controls whether ZXing-C++ returns barcode candidates with decoder errors.

Run Locally

python3.12 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
barcode-hub

Decode from a URL:

curl 'http://localhost:8080/decode?url=https://example.com/image.jpg&types=EAN13,UPCA'

Decode from a local file URL when deployment policy allows file://:

curl 'http://localhost:8080/decode?url=file:///data/input/image.png&types=EAN13'

Decode an uploaded file:

curl -F '[email protected];type=image/jpeg' 'http://localhost:8080/decode?types=EAN13'

Decode raw bytes:

curl -X PUT --data-binary @image.jpg -H 'Content-Type: image/jpeg' \
  'http://localhost:8080/decode?types=EAN13'

Docker

Use the prebuilt image from GitHub Container Registry:

docker pull ghcr.io/yiivgeny/barcode-hub:latest
docker run --rm -p 8080:8080 ghcr.io/yiivgeny/barcode-hub:latest

Or build locally:

docker build -t barcode-hub:local .
docker run --rm -p 8080:8080 barcode-hub:local

Docker Compose builds the local image by default:

docker compose up --build

Configuration

Configuration is loaded from /etc/barcode-hub/config.yaml when it exists. Set BARCODE_HUB_CONFIG to use another YAML path. Environment variables override file values. Nested variables use __ and the BARCODE_HUB_ prefix.

Example YAML:

app:
  host: 0.0.0.0
  port: 8080
limits:
  max_request_body_bytes: 16777216
  max_file_bytes: 8388608
  max_image_side_pixels: 4096
decode:
  enabled_methods: ["GET", "POST", "PUT"]
  default_formats: ["EAN13", "EAN8", "UPCA", "UPCE"]
  allowed_formats: ["EAN13", "EAN8", "UPCA", "UPCE", "QRCode", "DataMatrix"]
  request_timeout_seconds: 10
  max_side: null
  try_rotate: true
  try_downscale: true
  try_invert: false
  opencv:
    barcode_detector: true
  return_errors: true
fetch:
  timeout_seconds: 5
  allowed_url_prefixes: ["https://*.example.com/", "data:*", "file:///data/input/"]
media:
  allowed_content_types:
    ["image/png", "image/jpeg", "image/webp", "image/gif", "image/bmp", "image/tiff"]
mcp:
  enabled: true
logging:
  format: human
  level: INFO

Common environment variables:

• BARCODE_HUB_CONFIG
• BARCODE_HUB_APP__HOST
• BARCODE_HUB_APP__PORT
• BARCODE_HUB_LIMITS__MAX_REQUEST_BODY_BYTES
• BARCODE_HUB_LIMITS__MAX_FILE_BYTES
• BARCODE_HUB_LIMITS__MAX_IMAGE_SIDE_PIXELS
• BARCODE_HUB_DECODE__ENABLED_METHODS
• BARCODE_HUB_DECODE__DEFAULT_FORMATS
• BARCODE_HUB_DECODE__ALLOWED_FORMATS
• BARCODE_HUB_DECODE__REQUEST_TIMEOUT_SECONDS
• BARCODE_HUB_DECODE__MAX_SIDE
• BARCODE_HUB_DECODE__TRY_ROTATE
• BARCODE_HUB_DECODE__TRY_DOWNSCALE
• BARCODE_HUB_DECODE__TRY_INVERT
• BARCODE_HUB_DECODE__OPENCV__BARCODE_DETECTOR
• BARCODE_HUB_DECODE__RETURN_ERRORS
• BARCODE_HUB_FETCH__TIMEOUT_SECONDS
• BARCODE_HUB_FETCH__ALLOWED_URL_PREFIXES
• BARCODE_HUB_MEDIA__ALLOWED_CONTENT_TYPES
• BARCODE_HUB_MCP__ENABLED
• BARCODE_HUB_LOGGING__FORMAT
• BARCODE_HUB_LOGGING__LEVEL

allowed_url_prefixes are matched by parsing URLs. For example, https://*.example.com/ matches https://cdn.example.com/image.jpg, but does not match https://test.tld/example.com/image.jpg. file:///data/input/ matches local files under /data/input/; only local file: URLs with an empty host or localhost host are supported.

List settings should be supplied as YAML arrays in config files and JSON arrays in environment variables, for example ["GET","POST","PUT"]. BARCODE_HUB_FETCH__ALLOWED_URL_PREFIXES is the exception: supply it as a comma-separated string, for example http://*, https://*, data:*, file://*. Whitespace around entries is trimmed and empty entries from extra commas are ignored.

decode.max_side, when set, resizes the image with Lanczos before the first decode attempt if either image side is larger than that value. Response coordinates are mapped back to the original image space.

decode.opencv.barcode_detector enables a fallback through OpenCV's native barcode detector after ZXing-C++ returns no valid barcode. It is enabled by default and runs on the same image prepared by decode.max_side. OpenCV's barcode detector is used for supported linear retail codes; DataMatrix and other formats remain handled by ZXing-C++.

Metrics

/metrics includes process/platform/gc metrics and service metrics:

• barcode_hub_decode_requests_total{interaction,status}
• barcode_hub_decoded_barcodes_total{interaction,type,valid}
• barcode_hub_decode_request_duration_seconds{interaction,status}
• barcode_hub_recognition_duration_seconds{interaction,status}
• barcode_hub_resource_fetch_duration_seconds{interaction,status}
• barcode_hub_decode_input_bytes{interaction,source}
• barcode_hub_decode_image_max_side_pixels{interaction}
• barcode_hub_build_info

Interaction labels are get_url, post_multipart, put_binary, and mcp_url.

MCP

When enabled, /mcp exposes the decode_url tool:

decode_url(url: string, types?: list[BarcodeType]) -> DecodeResult

data:image/...;base64,... URLs and policy-enabled file: URLs are supported. MCP tool errors use MCP error semantics and stable domain codes in the message, such as invalid_url, disallowed_type, resource_timeout, and request_too_large.

Development

pip install -e '.[dev]'
python scripts/generate_contract.py --check
pytest
ruff check .

The shared response schema is spec/decode-result.schema.json. The OpenAPI contract is spec/openapi.yaml. The MCP contract is spec/mcp.md.

Runtime /openapi.json is loaded from spec/openapi.yaml and then narrowed by the active configuration: disabled /decode methods are removed, BarcodeType is limited to decode.allowed_formats, and request media types reflect media.allowed_content_types. The types query parameter default reflects decode.default_formats, and return_errors reflects decode.return_errors. Swagger UI and ReDoc use that runtime schema.

DecodeResult, Barcode, BarcodeType, and BarcodeValidity are generated from the Python models and format enum:

python scripts/generate_contract.py

The generator updates spec/decode-result.schema.json and only the marked components.schemas block in spec/openapi.yaml. Paths, request/response semantics, examples, and MCP documentation remain hand-authored.

License

Barcode Hub is MIT licensed. zxing-cpp is Apache-2.0 licensed; keep upstream notices when redistributing images or derived distributions.