ExPmtiles.Storage (ExPmtiles v0.3.4)

View Source

Storage adapter for PMTiles files, supporting both S3 and local file storage.

This module provides a unified interface for reading bytes from PMTiles files regardless of whether they are stored locally or in Amazon S3. It handles the different access patterns and error conditions for each storage type.

Storage Types

S3 Storage

  • Uses ExAws for S3 access
  • Supports range requests for efficient partial file reading
  • Configurable timeouts and connection pooling
  • Automatic error handling and logging

Local Storage

  • Direct file system access
  • Binary file reading with offset support
  • Automatic file handle management
  • Graceful error handling for missing files

Usage

# The module is used internally by ExPmtiles
# You typically don't call these functions directly

# For S3 files
instance = %ExPmtiles{source: :s3, bucket: "my-bucket", path: "file.pmtiles"}
data = ExPmtiles.Storage.get_bytes(instance, 0, 1024)

# For local files
instance = %ExPmtiles{source: :local, path: "/path/to/file.pmtiles"}
data = ExPmtiles.Storage.get_bytes(instance, 0, 1024)

Configuration

S3 requests use the following default configuration:

  • Receive timeout: 30 seconds
  • Connection pool: :s3_pool
  • Range request support for partial reads

Summary

Functions

get_bytes(instance, offset, length)

Retrieves a range of bytes from a PMTiles file.

get_file_metadata(instance, config \\ nil)

Retrieves file metadata for change detection.

Functions

get_bytes(instance, offset, length)

Retrieves a range of bytes from a PMTiles file.

This function automatically routes to the appropriate storage backend based on the instance's source type. It provides a unified interface for reading file data regardless of storage location.

Parameters

  • instance - The PMTiles instance containing storage configuration
  • offset - Byte offset in the file (0-based)
  • length - Number of bytes to read

Returns

  • binary() - The requested bytes
  • nil - If the bytes cannot be read (file not found, network error, etc.)

Examples

iex> instance = %ExPmtiles{source: :local, path: "test.pmtiles"}
iex> ExPmtiles.Storage.get_bytes(instance, 0, 1024)
<<...>>

iex> instance = %ExPmtiles{source: :s3, bucket: "bucket", path: "file.pmtiles"}
iex> ExPmtiles.Storage.get_bytes(instance, 1024, 512)
<<...>>

get_file_metadata(instance, config \\ nil)

Retrieves file metadata for change detection.

For S3 files, this returns the ETag which changes when the file is updated. For local files, this returns the last modified timestamp.

Parameters

  • instance - The PMTiles instance containing storage configuration
  • config - Optional ExAws config (primarily for testing with Bypass)

Returns

  • {:ok, metadata} - A string representing the file's current state (ETag or timestamp)
  • {:error, reason} - If metadata cannot be retrieved

Examples

iex> instance = %ExPmtiles{source: :s3, bucket: "bucket", path: "file.pmtiles"}
iex> ExPmtiles.Storage.get_file_metadata(instance)
{:ok, ""abc123def456""}

iex> instance = %ExPmtiles{source: :local, path: "test.pmtiles"}
iex> ExPmtiles.Storage.get_file_metadata(instance)
{:ok, "1702838400"}