buckets

defmodule Buckets.Router do
  @moduledoc """
  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
  """
  @scope "__buckets__"

  @doc """
  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__"
  """
  def scope(), do: @scope

  @doc """
  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.
  """
  defmacro buckets_volume(cloud_module, opts \\ []) do
    quote do
      scope unquote("/" <> @scope) do
        private = %{
          cloud_module: unquote(cloud_module),
          opts: unquote(opts)
        }

        get("/:bucket/*path", Buckets.Router.VolumeController, :get, private: private)
        put("/:bucket/*path", Buckets.Router.VolumeController, :put, private: private)
      end
    end
  end
end