Behaviour for SFTP storage backends.

See the HexDocs extras Backends and Custom Backends for package-level guidance before implementing this behaviour directly.

Implement this behaviour to create custom storage backends for the SFTP server. Built-in backends include:

• Sftpd.Backends.S3 - Amazon S3 or compatible object storage

Module-Based Backends

Implement the Sftpd.Backend behaviour:

defmodule MyApp.CustomBackend do
  @behaviour Sftpd.Backend

  @impl true
  def init(opts) do
    {:ok, %{root: opts[:root] || "/"}}
  end

  @impl true
  def list_dir(path, state) do
    {:ok, [~c".", ~c"..", ~c"file.txt"]}
  end

  # ... implement other callbacks
end

Then use it:

Sftpd.start_server(
  backend: MyApp.CustomBackend,
  backend_opts: [root: "/data"],
  ...
)

Process-Based Backends

For stateful backends, you can use a GenServer process instead:

Sftpd.start_server(
  backend: {:genserver, MyApp.BackendServer},
  ...
)

By default, the process receives the legacy message shapes:

def handle_call({:list_dir, path}, _from, state)
def handle_call({:file_info, path}, _from, state)
def handle_call({:make_dir, path}, _from, state)
def handle_call({:del_dir, path}, _from, state)
def handle_call({:delete, path}, _from, state)
def handle_call({:rename, src, dst}, _from, state)
def handle_call({:read_file, path}, _from, state)
def handle_call({:write_file, path, content}, _from, state)

Opt in to authenticated session context with {:genserver, server, session: true}. Session-aware processes must handle:

def handle_call({:list_dir, path, session}, _from, state)
def handle_call({:file_info, path, session}, _from, state)
def handle_call({:make_dir, path, session}, _from, state)
def handle_call({:del_dir, path, session}, _from, state)
def handle_call({:delete, path, session}, _from, state)
def handle_call({:rename, src, dst, session}, _from, state)
def handle_call({:read_file, path, session}, _from, state)
def handle_call({:write_file, path, content, session}, _from, state)

Each should reply with the same format as the behaviour callbacks.

Optional Streaming Callbacks

Module backends can implement optional streaming callbacks for more efficient large-file transfers:

• read_file_range/4
• begin_write/2
• write_chunk/4
• finish_write/2
• abort_write/2

When these callbacks are present, Sftpd.IODevice avoids buffering entire files in memory for reads and most writes.

Close Semantics

Erlang's stock :ssh_sftpd server ignores the return value of file_handler.close/2 and always reports close success to the client. Write failures can therefore only be surfaced reliably during active writes, not on close/final multipart completion.