A GenServer that monitors an SMB share directory for new files and processes them automatically.

HotFolder implements the "hot folder" pattern common in printing and document processing industries, where files dropped into a monitored directory trigger automated processing workflows.

Features

• Sequential Processing: Files are processed one at a time to ensure deterministic behavior
• Flexible Connection Management: Use existing connections or create new ones
• Rich File Filtering: Filter files by name patterns, size, and MIME types
• Automatic Folder Management: Creates and manages processing, success, and error folders
• Robust Error Handling: Retries failed processing with exponential backoff
• Efficient Polling: Smart polling with backoff to minimize network overhead

Basic Usage

# Simple configuration with direct connection
{:ok, pid} = Sambex.HotFolder.start_link(%{
  url: "smb://server/print-queue",
  username: "printer",
  password: "secret",
  handler: &MyApp.process_print_job/1
})

# Using an existing named connection
{:ok, pid} = Sambex.HotFolder.start_link(%{
  connection: :print_server,
  handler: &MyApp.process_print_job/1
})

Advanced Configuration

config = %Sambex.HotFolder.Config{
  connection: :print_server,
  base_path: "hot-folders/pdf-processor",
  handler: {MyApp.PDFProcessor, :process, [:high_quality]},

  folders: %{
    incoming: "inbox",
    processing: "working",
    success: "completed",
    errors: "failed"
  },

  filters: %{
    name_patterns: [~r/.pdf$/i],
    min_size: 1024,
    max_size: 100_000_000,  # 100MB
    exclude_patterns: [~r/^./, ~r/~$/]
  },

  poll_interval: %{
    initial: 1_000,
    max: 30_000,
    backoff_factor: 2.0
  },

  handler_timeout: 300_000,  # 5 minutes
  max_retries: 5
}

{:ok, pid} = Sambex.HotFolder.start_link(config)

File Processing Workflow

1. Discovery: Files are discovered in the incoming folder during polling
2. Filtering: Files are checked against configured filters
3. Stability Check: Files must have stable size to ensure complete upload
4. Processing: File is moved to processing folder and handler is called
5. Success: On success, file is moved to success folder
6. Error: On failure, file is moved to errors folder with error report

Handler Interface

Handlers receive a file info map and should return {:ok, result} or {:error, reason}:

def process_file(file_info) do
  # file_info contains: %{path: "...", name: "...", size: ...}
  case do_processing(file_info.path) do
    :ok -> {:ok, %{processed_at: DateTime.utc_now()}}
    {:error, reason} -> {:error, reason}
  end
end

Monitoring and Stats

# Get current statistics
Sambex.HotFolder.stats(pid)
# => %{files_processed: 150, files_failed: 3, uptime: 3600, ...}

# Get current status
Sambex.HotFolder.status(pid)
# => :polling | {:processing, "filename.pdf"} | :error