mimetype

mimetype is a Go library for detecting a file’s MIME type and extension using magic-number signatures instead of trusting file extensions or user-supplied Content-Type headers. It exposes Detect, DetectReader, and DetectFile functions that inspect the leading bytes of an input (limit configurable via SetLimit) and return a MIME value carrying the type string, extension, and parent hierarchy.

The library organizes hundreds of supported formats into a hierarchical detection tree rooted at application/octet-stream, so a specific format like DOCX is only checked once a file has already matched as a ZIP archive. It ships with zero external dependencies, is safe for concurrent use behind a shared RWMutex, and supports registering custom detectors for formats it doesn’t recognize out of the box via Extend().

What You Get

• Detect/DetectReader/DetectFile functions for byte slices, io.Reader values, and file paths
• A hierarchical MIME tree covering hundreds of formats rooted at application/octet-stream
• MIME.Is()/EqualsAny() helpers for alias-aware, spec-correct type comparisons instead of brittle string checks
• An Extend() API to register custom detectors for formats not built in
• A configurable read limit via SetLimit() to trade detection accuracy for performance on large files

Common Use Cases

• Validating uploaded file types in a web service instead of trusting the client-supplied Content-Type header
• Sniffing the MIME type of files read from disk or network before further processing
• Building content-type-aware pipelines such as image resizers, document converters, and virus scanners
• Extending detection to support proprietary or organization-specific binary formats

Under The Hood

Architecture The library implements a hierarchical detection tree (tree.go) rooted at a generic “application/octet-stream” node; each node (the MIME struct in mime.go) holds a detector function, extension, aliases, and children, and match() performs a depth-first walk that tries child detectors before falling back to the parent, so a specific format like DOCX is only probed once a file has already matched as ZIP. Concurrent access to the mutable tree used by Extend() is synchronized via a package-level sync.RWMutex, with read paths (Detect/DetectReader/DetectFile) taking a read lock for goroutine-safe concurrent detection. Detection functions live in internal/magic, grouped by format family (image, video, audio, archive, document, and more), each a small pure function of the raw bytes and a limit — this composability is what lets tree.go declare the full format catalog declaratively. Because every public entry point and every format detector walks the same tree, a change to the core MIME struct or match() dispatch logic would ripple through the whole detection surface.

Tech Stack This is a pure Go 1.21 module with zero runtime dependencies — go.mod declares none, and the public API relies only on the standard library (io, mime, os, sync/atomic, slices, strings). Internal helper packages (internal/magic, internal/charset, internal/csv, internal/json, internal/cdf, internal/markup, internal/mp3, internal/scan) hold the per-format matchers and byte-scanning utilities and are not exposed publicly. CI workflows (go.yml, benchmark.yml, fuzz.yml, codeql.yml) run tests, benchmarks, native Go fuzzing, and CodeQL static analysis on every change; distribution is the standard go get path with no extra build tooling.

Code Quality Tests are extensive: a large top-level test file exercises the public API, per-package tests cover the trickier format families in internal/magic (archives, text/CSV, ZIP-based formats), and testable Go examples double as living documentation. A testdata directory ships real sample files so format detection is checked against golden fixtures rather than synthetic input, and the project’s contribution guidance requires new format detectors to be test-covered and gofmt-formatted. A dedicated fuzzing workflow and CodeQL static analysis add scrutiny above what’s typical for a library this size. Error handling favors returning a safe default MIME value alongside any read error rather than panicking, and the exported surface stays narrow and consistently typed.

API Design The public API is deliberately small and consistent: three detection entry points (Detect, DetectReader, DetectFile) all return the same MIME type, with String()/Extension()/Is()/Parent() methods giving ergonomic access without exposing the underlying tree; MIME.Is() steers callers away from brittle string comparisons, and EqualsAny() covers the common multi-type check in one call. Getting started needs no configuration — a single Detect(data) call works out of the box — while SetLimit() and Extend() are opt-in escape hatches for advanced tuning and custom format support, keeping the common path free of boilerplate.