internal/

README

Internal Packages - Developer Guide

Version: 1.0.0 Last Updated: 2025-12-20

This document provides guidelines for developing internal packages within the JPEG library. All internal packages should follow these conventions to maintain consistency across the codebase.

Logging Infrastructure

The JPEG library uses structured logging via the github.com/0verkilll/logger package. All internal packages MUST use the logging patterns described here.

Log Levels

Use the appropriate log level based on the type of information:

Level	Function	When to Use
Debug	logger.Debug()	Detailed technical information for debugging. Use for marker offsets, coefficient values, parsing steps.
Info	logger.Info()	Significant events in normal operation. Use for format detection, decode start/completion.
Warn	logger.Warn()	Potentially problematic situations. Use for deprecated features, fallback behaviors, recoverable errors.
Error	logger.Error()	Error conditions that don't halt execution. Use for malformed data that can be skipped, optional feature failures.

Import Pattern for Internal Packages

All internal packages should import the logger package directly:

import (
    "github.com/0verkilll/logger"
)

Structured Logging Keys

Use consistent key names across all packages:

Key	Type	Description
"offset"	int	Byte offset in the data stream
"marker"	string/int	JPEG marker type (e.g., "SOF0", 0xC0)
"format"	string	File format being processed
"width"	int	Image width in pixels
"height"	int	Image height in pixels
"component"	int	Component index (0=Y, 1=Cb, 2=Cr)
"block"	int	Block index in scan order
"value"	int/float	Decoded or computed value
"error"	error	Error object for context
"size"	int	Size in bytes
"table"	int	Table index (Huffman, quantization)

Example Code Snippets

Debug Logging - Marker Parsing

func (d *Decoder) parseMarker(offset int, markerType byte) {
    logger.Debug("parsing marker",
        "offset", offset,
        "marker", fmt.Sprintf("0x%02X", markerType),
        "format", "JPEG",
    )
    // ... parsing logic
}

Info Logging - Decode Start/Complete

func (d *Decoder) Decode() ([]int, error) {
    logger.Info("starting decode",
        "format", d.formatName,
        "width", d.width,
        "height", d.height,
    )

    // ... decode logic

    logger.Info("decode complete",
        "format", d.formatName,
        "coefficients", len(result),
    )
    return result, nil
}

Warn Logging - Fallback Behavior

func (d *Decoder) processBlock(blockIdx int) {
    if d.quantTable == nil {
        logger.Warn("missing quantization table, using default",
            "block", blockIdx,
            "table", d.quantTableID,
        )
        d.quantTable = defaultQuantTable
    }
    // ... block processing
}

Error Logging - Recoverable Error

func (d *Decoder) decodeCoefficient(k int) (int, error) {
    value, err := d.readValue()
    if err != nil {
        logger.Error("failed to decode coefficient, using zero",
            "block", d.currentBlock,
            "coefficient", k,
            "error", err,
        )
        return 0, nil // Recoverable - continue with zero
    }
    return value, nil
}

NopLogger for Zero Overhead

When no logger is configured (the default), all logging calls are no-ops with zero allocations. The library uses NopLogger which immediately returns without processing arguments:

// NopLogger has zero overhead - safe for hot paths
type NopLogger struct{}

func (l *NopLogger) Debug(_ string, _ ...any) {}
func (l *NopLogger) Info(_ string, _ ...any) {}
func (l *NopLogger) Warn(_ string, _ ...any) {}
func (l *NopLogger) Error(_ string, _ ...any) {}

Testing with Logging

In tests, you can capture log output for verification:

func TestDecoderLogging(t *testing.T) {
    // Set up a test logger that captures output
    var buf bytes.Buffer
    testLogger := logger.NewLogger(
        logger.WithWriter(&buf),
        logger.WithLevel(logger.LevelDebug),
    )
    logger.SetLogger(testLogger)
    defer logger.SetLogger(nil)

    // Run decode
    decoder := NewDecoder(testData)
    _, _ = decoder.Decode()

    // Verify log output
    output := buf.String()
    if !strings.Contains(output, "parsing marker") {
        t.Error("expected marker parsing to be logged")
    }
}

Internationalization (i18n)

All user-facing error messages MUST use the translation system.

Import Pattern

import (
    "github.com/0verkilll/i18n"
)

Error Message Pattern

// Define a translate helper in each package
func translate(key string, args ...any) string {
    return i18n.T(key, args...)
}

// Use in error creation
func (d *Decoder) validateHeader() error {
    if d.width == 0 {
        return fmt.Errorf(translate("jpeg.error.invalid_width"))
    }
    return nil
}

Translation Key Convention

All keys should follow this naming pattern:

jpeg.<package>.<category>.<specific>

Examples:

• jpeg.huffman.error.invalid_table
• jpeg.jpegls.decode.start
• jpeg.jpeg2000.wavelet.level

Security Requirements

Safe Integer Conversions

All internal packages MUST use the internal/safeconv package for integer conversions:

import "github.com/0verkilll/jpeg/internal/safeconv"

func (d *Decoder) allocateBuffer(size int64) ([]byte, error) {
    bufSize, err := safeconv.Int64ToInt(size)
    if err != nil {
        return nil, fmt.Errorf("buffer size overflow: %w", err)
    }
    return make([]byte, bufSize), nil
}

Buffer Size Validation

Always validate buffer sizes against security limits before allocation:

const maxBufferSize = 536870912 // 512MB

func (d *Decoder) decode() error {
    bufferSize := int64(d.width) * int64(d.height) * int64(d.components)
    if bufferSize > maxBufferSize {
        return fmt.Errorf("buffer size %d exceeds maximum %d", bufferSize, maxBufferSize)
    }
    // ... allocate and use buffer
}

Package Structure

Each internal package should follow this structure:

internal/<package>/
    doc.go        # Package documentation
    types.go      # Type definitions and constants
    errors.go     # Package-specific errors
    decoder.go    # Main decoder implementation
    encoder.go    # Main encoder implementation (if applicable)
    *_test.go     # Unit tests
    fuzz_test.go  # Fuzz tests (required for all decoders)

Testing Requirements

Unit Tests

• Each package MUST have unit tests with at least 80% coverage
• Use table-driven tests for multiple scenarios
• Test error paths, not just happy paths

Fuzz Tests

All decoder packages MUST include fuzz tests:

func FuzzDecode(f *testing.F) {
    // Add seed corpus
    f.Add([]byte{0xFF, 0xD8, 0xFF, 0xE0})

    f.Fuzz(func(t *testing.T, data []byte) {
        d := NewDecoder(data)
        _, _ = d.Decode() // Must not panic
    })
}

---

These guidelines ensure consistent, maintainable, and secure code across all internal packages.