Skip to content

Channels

themarioga edited this page Nov 8, 2026 · 1 revision

Channels

A channel is where files come from (imports) or go to (exports, reports and deliverFile).

Channel Input Output
LocalDirectoryChannel Regular files directly inside the directory Delivery into the directory
SftpChannel Files of remoteDirectory, downloaded before reading Upload into remoteDirectory
ProvidedStreamChannel Streams in ImportContext.providedInputs ExportContext.providedOutput

Local directory

LocalDirectoryChannel.of(Path.of("/data/in"))
new LocalDirectoryChannel(Path.of("/data/out"), 10_000_000L /* maxFileSize */, OnExistingFile.FAIL)

On input the listed file itself is the local copy. A missing directory fails the run with CHANNEL.

SFTP

SftpChannel.builder()
        .host("sftp.example.com")
        .port(22)                                         // default
        .username("tie")
        .password("${secret:sftp}")                       // or privateKey(pem) or privateKeyFile(path)
        .remoteDirectory("/in")
        .knownHostsFile(Path.of("/etc/tie/known_hosts"))  // or hostKeyFingerprint("SHA256:…")
        .timeout(Duration.ofSeconds(30))                  // default
        .maxFileSize(50_000_000L)
        .build();

Authentication

Exactly one of:

  • password;
  • privateKey: the PEM or OpenSSH content of the key;
  • privateKeyFile: a path to the key;

and, for a key, an optional privateKeyPassphrase. password, privateKey and privateKeyPassphrase accept a literal or ${secret:name}, resolved by the SecretProvider registered in Tie when connecting; the returned char[] is cleared afterwards. A rejected credential is an AUTHENTICATION error; its message never contains the credential.

Host keys

The server identity is always verified:

Setting Check
knownHostsFile OpenSSH known_hosts, strict ([host]:port entries for non-standard ports)
hostKeyFingerprint SHA256 fingerprint as OpenSSH prints it: SHA256:…
insecureAcceptAnyHostKey(true) Any key; a WARN naming the option is logged on every connection

Exactly one of them is required. A mismatch is a HOST_KEY error ("host key verification failed").

Timeouts

timeout applies to connecting and to each transfer: a download or upload without progress for that long is cut, and the file fails with CHANNEL. SSH keepalives detect dropped connections.

Input behaviour

  • The session opens when listing and stays open for the run.
  • Each file is downloaded entirely into the working directory before it is read, and the copy is deleted when the file ends, whatever the outcome.
  • A file that disappears between listing and download fails with CHANNEL ("no longer exists").
  • maxFileSize is checked against the listed size, before downloading.
  • MOVE(folder) is relative to remoteDirectory unless it starts with /; the folder must exist. A name already in the folder gets a .<epochMillis> suffix.

Provided streams

ImportContext.builder(consumer)
        .providedInput("person", "upload.csv", inputStream)
        .build();

The definition needs a ProvidedStreamChannel among its inputChannels. A provided input names its layout and file name (the extension selects the format). It skips name patterns, watermarks, the already-processed predicate, file hooks and post-success actions, and never moves a watermark. Provided inputs are processed after the files of the other channels, in list order, and TIE closes every stream, also when it is not processed.

For exports, ExportContext.providedOutput(() -> outputStream) receives the whole file when the export succeeds; TIE closes the stream.

Delivery rules

Exports, result reports and deliverFile share the same delivery:

  1. The file is uploaded or copied under a temporary name, .<name>.part, in the destination.
  2. It is renamed to its final name. A partial file never appears under the final name.
  3. If the final name exists, onExistingFile decides:
onExistingFile Result
SUFFIX (default) Delivered as <base>.<epochMillis>.<ext>
FAIL NAME_COLLISION; the existing file is untouched
OVERWRITE Replaced. On SFTP the existing file is removed and then renamed: not atomic

A name created by someone else while the copy is running is handled the same way. If the temporary file cannot be removed after a failure, the result carries a TEMP_CLEANUP_FAILED warning.

Clock

Name timestamps and collision suffixes use the Clock of Tie (Tie.builder().clock(...)), so tests can fix it.

Clone this wiki locally