Assets Package

The assets package provides utilities for working with gzip-compressed embedded file systems, allowing transparent decompression of .gz files.

Import

import "github.com/prometheus/common/assets"

Overview

This package wraps Go's embed.FS to provide transparent gzip decompression when opening files. Files with .gz extension are automatically decompressed on read, and the file information is adjusted to reflect the actual decompressed size and name (without .gz extension).

Core Types

FileSystem

type FileSystem struct {
    // Wraps an embed.FS to provide transparent gzip decompression
}

Wraps an embed.FS to provide transparent gzip decompression. Implements the fs.FS interface.

Methods

func (fs FileSystem) Open(path string) (fs.File, error)

Opens a file from the embedded filesystem. First attempts to open the path as-is (for directories and uncompressed files). If not found, tries to open the file with a .gz suffix added and automatically decompresses it. Returns an fs.File that provides access to the (possibly decompressed) content.

File

type File struct {
    // Represents a file that may be compressed
}

Represents a file from the FileSystem. Implements fs.File interface.

Methods

func (f File) Stat() (fs.FileInfo, error)

Returns file info with adjusted size and name (without .gz extension for compressed files).

func (f *File) Read(buf []byte) (int, error)

Reads decompressed content into the buffer.

func (f File) Close() error

Closes the underlying file.

FileInfo

type FileInfo struct {
    // Wraps fs.FileInfo to return actual decompressed size
}

Wraps fs.FileInfo to return the actual decompressed size and name without .gz extension. Implements fs.FileInfo interface.

Methods

func (fi FileInfo) Name() string

Returns the filename without .gz extension.

func (fi FileInfo) Size() int64

Returns the actual decompressed size.

func (fi FileInfo) Mode() fs.FileMode

Returns the file mode.

func (fi FileInfo) ModTime() time.Time

Returns the modification time.

func (fi FileInfo) IsDir() bool

Returns whether this is a directory.

func (fi FileInfo) Sys() interface{}

Returns the underlying data source (always nil).

Functions

New

func New(fs embed.FS) FileSystem

Creates a new FileSystem wrapping the given embed.FS. The returned FileSystem can be used anywhere an fs.FS is expected, and will transparently decompress .gz files.

Parameters:

• fs - The embedded filesystem to wrap

Returns: A FileSystem that provides transparent gzip decompression

Usage Example

package main

import (
    "embed"
    "io"
    "log"

    "github.com/prometheus/common/assets"
)

//go:embed static/*
var staticFiles embed.FS

func main() {
    // Create a FileSystem with gzip support
    fs := assets.New(staticFiles)

    // Open a gzipped file - it will be automatically decompressed
    file, err := fs.Open("static/index.html.gz")
    if err != nil {
        log.Fatal(err)
    }
    defer file.Close()

    // Read the decompressed content
    content, err := io.ReadAll(file)
    if err != nil {
        log.Fatal(err)
    }

    // File info shows the decompressed name and size
    info, _ := file.Stat()
    log.Printf("File: %s, Size: %d bytes", info.Name(), info.Size())
    // Output: File: index.html, Size: <actual decompressed size> bytes
}

Integration with http.FileServer

The FileSystem can be used directly with Go's http.FileServer:

import (
    "embed"
    "net/http"

    "github.com/prometheus/common/assets"
)

//go:embed static/*
var staticFiles embed.FS

func main() {
    fs := assets.New(staticFiles)
    http.Handle("/static/", http.StripPrefix("/static/", http.FileServer(http.FS(fs))))
    http.ListenAndServe(":8080", nil)
}