Buckets.Router (buckets v1.0.0-rc.2)

Router helpers for integrating Buckets with Phoenix applications.

This module provides macros for setting up development routes that handle file uploads and downloads when using the Volume adapter. These routes enable direct file uploads to the local filesystem during development, mimicking the behavior of cloud storage providers.

Usage

Import this module in your Phoenix router and use the buckets_volume/2 macro to set up the necessary routes:

# In your router.ex
defmodule MyAppWeb.Router do
  use MyAppWeb, :router

  # Only include in development
  if Application.compile_env(:my_app, :dev_routes) do
    import Buckets.Router

    # Sets up routes at /__buckets__/:bucket/*path
    buckets_volume(MyApp.Cloud)
  end
end

Routes Created

The macro creates two routes under the /__buckets__ scope:

  • GET /__buckets__/:bucket/*path - Download files
  • PUT /__buckets__/:bucket/*path - Upload files

Security

These routes validate:

  • The bucket name matches the configured bucket
  • Upload requests have valid signatures (generated by the Volume adapter)

Configuration

The routes can be customized with options:

buckets_volume(MyApp.Cloud, cache_control: 3600)

Available options are passed to the controller and may include:

  • :cache_control - Max age in seconds for cache control headers

Summary

Functions

Sets up Volume adapter routes for local file handling in development.

Returns the default scope path used for Buckets routes.

Functions

Link to this macro

buckets_volume(cloud_module, opts \\ [])

(macro)

Sets up Volume adapter routes for local file handling in development.

This macro creates GET and PUT routes under the /__buckets__ scope that handle file downloads and uploads respectively. It's designed to be used with the Volume adapter during development to provide a local alternative to cloud storage.

Parameters

  • cloud_module - The Cloud module to use for configuration (e.g., MyApp.Cloud)
  • opts - Optional keyword list of options:
    • :cache_control - Max age in seconds for cache control headers

Examples

# Basic usage
buckets_volume(MyApp.Cloud)

# With cache control
buckets_volume(MyApp.Cloud, cache_control: 3600)

Routes Created

The following routes are created:

  • GET /__buckets__/:bucket/*path - Downloads a file from the local filesystem
  • PUT /__buckets__/:bucket/*path - Uploads a file to the local filesystem

Both routes include the cloud module and options in the connection's private data for use by the VolumeController.

Security Note

These routes should only be used in development. The macro includes validation to ensure the bucket parameter matches the configured bucket and that uploads include valid signatures.

Returns the default scope path used for Buckets routes.

This is useful if you need to reference the scope in your own code or need to know where the routes are mounted.

Examples

iex> Buckets.Router.scope()
"__buckets__"