DodoTech-Public/DodoSSH
Public Access
2
0
Fork 0
Code Issues Pull Requests 2 Actions 2 Packages Projects Releases 2 Wiki Activity

Move files to and from a host over SFTP

Browse Source 
M2's file transfer, built bottom-up: an SFTP session on the SSH layer, a
transfer queue in a project of its own, and the two-pane browser the design
asked for replacing the screen that said it did not exist. Remote listings
carry names, sizes, modification times and a real drwxr-xr-x — nothing in this
repository could render a POSIX mode before — and the queue moves one file at a
time with progress, throughput and resume.

The design import assumed this would be an SFTP subsystem channel on
ISshConnection, beside the shell on a transport that is already up. SSH.NET
does not offer that: SftpClient derives from BaseClient and owns its own
transport, and there is no supported way to hand it an SshClient's session. So
file transfer opens a second authenticated connection, and it is named for
that rather than dressed up as a channel — OpenSftpAsync is on
ISftpSessionFactory, not on a connection. The difference is visible to a user:
the host records a second login, and a host whose password is typed each time
asks for it again on this screen. It goes through the same host key gate, the
same pin and the same two refusals a shell does, so a fingerprint approved for
a terminal is approved here and one approved here reaches the other machines
with the next sync. docs/design-import-gaps.md is corrected, and marked as the
one row where what shipped differs from what it predicted.

Nothing is written at its final name until it is complete. Every transfer goes
to a .dodossh-part file beside its destination and is renamed into place at the
end, so an interrupted transfer can never be mistaken for a finished one —
which matters most for what this screen is actually for, which is copying a
build artefact onto a server and then running it. A destination that already
exists is refused outright rather than overwritten: the queue has no way to
ask, and silently replacing a file somebody's process is serving is the worse
of the two failures. The remote pane has DELETE and MKDIR so that refusal is
not a dead end. A test against the container pins the assumption underneath all
of this — that SFTP's rename does not clobber.

Resume works within a run of the application and not across a restart, and the
limit is deliberate rather than unfinished. Nothing records which source wrote
a part file, and resuming one on the strength of its name matching is how a
corrupt artefact gets delivered with nothing reporting a failure; a part file
found at startup is started over. Making it survive a restart needs the
preferences store this client still has not got. The offset a resume starts at
is the part file's own length rather than the transfer's recorded progress: a
cancellation can land between a write completing and the counter moving, and
only one of those two is a fact about the bytes that are there.

The queue and its connection outlive a lock, as shells do. LockAsync already
argues that locking must not destroy work in flight — it is what somebody does
when they walk away from the machine, which is exactly when a long transfer is
most likely to be running — so TransfersViewModel is created once and the vault
is attached on unlock and detached on lock. What locking takes is the host
list, and it has to: those rows carry decrypted secrets.

DodoSSH.Client.Transfer is a new project rather than more of Client.Ssh. The
two answer different questions — one is about reaching a host, the other about
moving bytes and what to do when moving them stops halfway — and this is the
only client project that deliberately touches the local filesystem.

Three defects the tests found, none of which review would have. SftpPath.Name
answered an empty string for the root. NavigateRemoteAsync wrapped itself in
the busy guard, so navigating from inside another command did nothing at all
and the remote pane simply stayed empty after connecting, with no failure
anywhere to explain it. And opening an SFTP session per test made two
handshakes per test — this client learns a host key by being refused — which
pushed the SSH assembly past sshd's MaxStartups and failed a different few
unrelated tests each run; the session is shared through the fixture now, with
the reason written where the next person will hit it.

1004 tests green across 18 projects, 24 of them new: the SFTP subsystem against
the OpenSSH container, the queue against a real temporary directory and a fake
host, and three more layout measurements because a screen this window has never
laid out is a screen never checked.

Not verified: the screen has not been looked at running. The layout harness
measures it at the window's minimum in three shapes, which is the class of
defect that has shipped here before, but reaching it in the application needs
the compose stack, the migrations, the API and a browser sign-in. What is still
absent — the status bar's transfer count, dragging between the panes,
transferring a directory, and sftp over a bastion — is in
docs/design-import-gaps.md.
This commit is contained in:
jaap-jan
2026-07-31 11:07:29 +02:00
parent 94e11f5e38
commit 04faef6597
32 changed files with 4933 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/DodoSSH.Client.Ssh.Tests/RemotePathTests.cs
+99
View File
@@ -0,0 +1,99 @@
namespace DodoSSH.Client.Ssh.Tests;
/// <summary>
/// Remote paths, permission bits and byte counts — the three things the file browser renders.
/// </summary>
/// <remarks>
/// Not in the SSH collection, so this class needs no container. Every case here is one where the obvious
/// implementation is wrong on Windows, at a filesystem root, or on a number that has just crossed a
/// threshold — which is to say, one that a listing of somebody's home directory would not reveal.
/// </remarks>
public sealed class RemotePathTests
{
[Theory]
[InlineData("/var/log", "syslog", "/var/log/syslog")]
[InlineData("/", "etc", "/etc")]
[InlineData("/home/dodo/", "notes", "/home/dodo/notes")]
public void Combine_JoinsWithExactlyOneSeparator(string directory, string name, string expected)
{
// Deliberately not Path.Combine, which on Windows would yield "/var/log\syslog" — a path the remote
// cannot resolve, failing as "no such file" somewhere the backslash is invisible.
SftpPath.Combine(directory, name).ShouldBe(expected);
}
[Theory]
[InlineData("/var/log/syslog", "/var/log")]
[InlineData("/var/log", "/var")]
[InlineData("/var", "/")]
[InlineData("/", "/")]
[InlineData("/var/log/", "/var")]
public void Parent_StopsAtTheRoot(string path, string expected)
{
// The root is its own parent rather than null, which is what lets the breadcrumb's "up" be a plain
// navigation with nothing above it to special-case.
SftpPath.Parent(path).ShouldBe(expected);
}
[Theory]
[InlineData("/var/log/syslog", "syslog")]
[InlineData("/var/log/", "log")]
[InlineData("/", "/")]
public void Name_IsTheLastSegment(string path, string expected)
{
SftpPath.Name(path).ShouldBe(expected);
}
[Fact]
public void Trail_NamesEverySegmentWithThePathThatReachesIt()
{
SftpPath.Trail("/var/log/nginx").ShouldBe(
[("var", "/var"), ("log", "/var/log"), ("nginx", "/var/log/nginx")]);
}
[Fact]
public void Trail_IsEmptyAtTheRoot()
{
// The root has no segment to name. The breadcrumb draws it as a leading separator, so a trail with a
// phantom empty crumb in it would render as a button with no label.
SftpPath.Trail("/").ShouldBeEmpty();
}
[Fact]
public void PosixMode_RendersTheKindCharacterAndThreeTriples()
{
PosixMode.Format(
SftpEntryKind.Directory,
ownerRead: true, ownerWrite: true, ownerExecute: true,
groupRead: true, groupWrite: false, groupExecute: true,
othersRead: true, othersWrite: false, othersExecute: true)
.ShouldBe("drwxr-xr-x");
PosixMode.Format(
SftpEntryKind.File,
ownerRead: true, ownerWrite: true, ownerExecute: false,
groupRead: true, groupWrite: false, groupExecute: false,
othersRead: false, othersWrite: false, othersExecute: false)
.ShouldBe("-rw-r-----");
PosixMode.Format(
SftpEntryKind.SymbolicLink,
ownerRead: true, ownerWrite: true, ownerExecute: true,
groupRead: true, groupWrite: true, groupExecute: true,
othersRead: true, othersWrite: true, othersExecute: true)
.ShouldBe("lrwxrwxrwx");
}
[Theory]
[InlineData(0, "0 B")]
[InlineData(1023, "1023 B")]
[InlineData(1024, "1.0 KB")]
[InlineData(10 * 1024, "10 KB")]
[InlineData(1536 * 1024, "1.5 MB")]
[InlineData(5L * 1024 * 1024 * 1024, "5.0 GB")]
public void ByteSize_KeepsOneDecimalOnlyWhileItMeansSomething(long bytes, string expected)
{
// The boundary at ten is the whole rule: "9.4 MB" and "512 MB" carry the same information, and
// "512.3 MB" claims a precision the figure does not have by the time it is that large.
ByteSize.Format(bytes).ShouldBe(expected);
}
}
tests/DodoSSH.Client.Ssh.Tests/SftpSessionTests.cs
+262
View File
@@ -0,0 +1,262 @@
using System.Text;
namespace DodoSSH.Client.Ssh.Tests;
/// <summary>
/// The SFTP subsystem, against a real sshd.
/// </summary>
/// <remarks>
/// <para>
/// Everything this suite is about is behaviour of a server rather than of this code: whether a listing
/// carries the permission bits the design's <c>PERMS</c> column needs, whether opening at an offset really
/// starts there, and whether a rename over a name that already exists fails rather than silently replacing —
/// which the transfer queue's part-file scheme depends on. None of it can be established against a mock.
/// </para>
/// <para>
/// One directory per test, named after it, because the container is shared with every other suite in the
/// assembly and a test that cleaned up by emptying the home directory would take another test's fixture with
/// it. The <em>session</em> is shared too, and that is a limit of the server rather than tidiness — see
/// <see cref="SshServerFixture.SftpAsync"/>, which explains what opening one per test did to the rest of the
/// assembly.
/// </para>
/// </remarks>
[Collection(SshCollection.Name)]
public sealed class SftpSessionTests(SshServerFixture fixture)
{
private static CancellationToken Token => TestContext.Current.CancellationToken;
[Fact]
public async Task AnOpenedSession_StartsInTheAccountsHomeDirectory()
{
var sftp = await fixture.SftpAsync(Token);
// Absolute, because the server canonicalises it during the handshake. A relative answer would make
// every path the browser builds relative too, and the breadcrumb trail meaningless.
SftpPath.IsAbsolute(sftp.HomeDirectory).ShouldBeTrue(sftp.HomeDirectory);
sftp.IsConnected.ShouldBeTrue();
}
[Fact]
public async Task AListing_CarriesKindSizeAndPermissions()
{
var sftp = await fixture.SftpAsync(Token);
var directory = await MakeDirectoryAsync(sftp, nameof(AListing_CarriesKindSizeAndPermissions));
var content = "the quick brown fox"u8.ToArray();
await WriteAsync(sftp, SftpPath.Combine(directory, "a-file"), content);
await sftp.CreateDirectoryAsync(SftpPath.Combine(directory, "a-directory"), Token);
var entries = await sftp.ListAsync(directory, Token);
// Directories first: the order this interface promises, and what the file browser shows without
// sorting again.
entries.Select(entry => entry.Name).ShouldBe(["a-directory", "a-file"]);
var file = entries[1];
file.Kind.ShouldBe(SftpEntryKind.File);
file.Length.ShouldBe(content.Length);
file.FullPath.ShouldBe(SftpPath.Combine(directory, "a-file"));
// The one column nothing in this repository could render before. The exact bits depend on the
// server's umask, so what is pinned is the shape and the kind character rather than the mode.
file.Permissions.Length.ShouldBe(10);
file.Permissions[0].ShouldBe('-');
file.Permissions.ShouldStartWith("-rw");
entries[0].Kind.ShouldBe(SftpEntryKind.Directory);
entries[0].Permissions[0].ShouldBe('d');
}
[Fact]
public async Task AListing_DropsTheDotEntries()
{
var sftp = await fixture.SftpAsync(Token);
var directory = await MakeDirectoryAsync(sftp, nameof(AListing_DropsTheDotEntries));
// Empty, which is the case where "." and ".." are the whole listing — so a browser that showed them
// would present an empty directory as one holding two things.
var entries = await sftp.ListAsync(directory, Token);
entries.ShouldBeEmpty();
}
[Fact]
public async Task ListingSomethingThatIsNotADirectory_FailsWithThePath()
{
var sftp = await fixture.SftpAsync(Token);
var directory = await MakeDirectoryAsync(
sftp, nameof(ListingSomethingThatIsNotADirectory_FailsWithThePath));
var file = SftpPath.Combine(directory, "not-a-directory");
await WriteAsync(sftp, file, "x"u8.ToArray());
// The path is the whole point of the translation. SSH.NET's own exception for this carries the
// server's message and nothing about which path was asked for, and the browser has to say which
// row failed.
var failure = await Should.ThrowAsync<SftpPathException>(async () =>
await sftp.ListAsync(file, Token));
failure.Path.ShouldBe(file);
}
[Fact]
public async Task Stat_AnswersNullForSomethingThatIsNotThere()
{
var sftp = await fixture.SftpAsync(Token);
var directory = await MakeDirectoryAsync(
sftp, nameof(Stat_AnswersNullForSomethingThatIsNotThere));
// Absent is an answer rather than a failure: the transfer queue asks this before every upload to
// find out whether it would be overwriting something, and that question has a "no".
(await sftp.StatAsync(SftpPath.Combine(directory, "nothing-here"), Token)).ShouldBeNull();
}
[Fact]
public async Task OpeningAtAnOffset_ReadsFromThere()
{
var sftp = await fixture.SftpAsync(Token);
var directory = await MakeDirectoryAsync(sftp, nameof(OpeningAtAnOffset_ReadsFromThere));
var path = SftpPath.Combine(directory, "resumable");
await WriteAsync(sftp, path, "0123456789"u8.ToArray());
// The whole of resume, in one call. If the server ignored the offset this would read the file from
// the start and a resumed download would silently duplicate its first half.
var stream = await sftp.OpenReadAsync(path, 4, Token);
await using var scope = stream.ConfigureAwait(false);
using var reader = new StreamReader(stream, Encoding.UTF8);
(await reader.ReadToEndAsync(Token)).ShouldBe("456789");
}
[Fact]
public async Task WritingAtAnOffset_LeavesWhatWasAlreadyThere()
{
var sftp = await fixture.SftpAsync(Token);
var directory = await MakeDirectoryAsync(sftp, nameof(WritingAtAnOffset_LeavesWhatWasAlreadyThere));
var path = SftpPath.Combine(directory, "appended");
await WriteAsync(sftp, path, "0123"u8.ToArray());
var stream = await sftp.OpenWriteAsync(path, 4, Token);
await using (stream.ConfigureAwait(false))
{
await stream.WriteAsync("456789"u8.ToArray(), Token);
await stream.FlushAsync(Token);
}
// The other half of resume: an upload that carried on from an offset must not have truncated the
// bytes an earlier attempt already delivered.
(await ReadAllAsync(sftp, path)).ShouldBe("0123456789");
}
[Fact]
public async Task Rename_RefusesToReplaceSomethingThatIsAlreadyThere()
{
var sftp = await fixture.SftpAsync(Token);
var directory = await MakeDirectoryAsync(
sftp, nameof(Rename_RefusesToReplaceSomethingThatIsAlreadyThere));
var part = SftpPath.Combine(directory, "artefact.dodossh-part");
var destination = SftpPath.Combine(directory, "artefact");
await WriteAsync(sftp, part, "new"u8.ToArray());
await WriteAsync(sftp, destination, "old"u8.ToArray());
// The transfer queue's last step, and the assumption underneath its promise never to overwrite: it
// checks the destination before starting, and this is what stops a file that appeared in the
// meantime from being replaced anyway. SFTP's rename is specified not to clobber, and this is the
// check that the server this project tests against actually behaves that way.
await Should.ThrowAsync<SftpPathException>(async () =>
await sftp.RenameAsync(part, destination, Token));
(await ReadAllAsync(sftp, destination)).ShouldBe("old");
}
[Fact]
public async Task DeletingANonEmptyDirectory_Fails()
{
var sftp = await fixture.SftpAsync(Token);
var directory = await MakeDirectoryAsync(sftp, nameof(DeletingANonEmptyDirectory_Fails));
await WriteAsync(sftp, SftpPath.Combine(directory, "occupant"), "x"u8.ToArray());
// Deliberate, and the reason this interface has no recursive delete: the one destructive operation
// on the transfers screen must not be able to take a directory tree with it.
await Should.ThrowAsync<SftpPathException>(async () => await sftp.DeleteAsync(directory, Token));
}
[Fact]
public async Task AnUntrustedHost_IsRefusedExactlyAsAShellWouldBe()
{
var factory = new SshNetConnectionFactory(new InMemoryKnownHostStore());
// File transfer opens its own connection, so it makes its own first-contact decision. The failure
// that matters is the one this asserts is *not* raised: a bare connection error would send the user
// looking at the network for what is a fingerprint they have not approved.
var refusal = await Should.ThrowAsync<SshHostKeyUnknownException>(async () =>
await factory.OpenSftpAsync(Request(), Token));
refusal.Presentation.Host.ShouldBe(fixture.Host);
refusal.Presentation.Fingerprint.ShouldStartWith("SHA256:");
}
private SshConnectionRequest Request() => new(
fixture.Host,
fixture.Port,
SshServerFixture.Username,
new SshPasswordCredential(SshServerFixture.Password));
/// <summary>A directory of this test's own, under the account's home.</summary>
private static async Task<string> MakeDirectoryAsync(ISftpSession sftp, string name)
{
var path = SftpPath.Combine(sftp.HomeDirectory, $"sftp-{name}");
if (await sftp.StatAsync(path, Token) is not null)
{
// A previous run of the same test in a container that outlived it. Emptying it is enough:
// nothing here creates nested directories.
foreach (var entry in await sftp.ListAsync(path, Token))
{
await sftp.DeleteAsync(entry.FullPath, Token);
}
return path;
}
await sftp.CreateDirectoryAsync(path, Token);
return path;
}
private static async Task WriteAsync(ISftpSession sftp, string path, byte[] content)
{
var stream = await sftp.OpenWriteAsync(path, 0, Token);
await using (stream.ConfigureAwait(false))
{
await stream.WriteAsync(content, Token);
await stream.FlushAsync(Token);
}
}
private static async Task<string> ReadAllAsync(ISftpSession sftp, string path)
{
var stream = await sftp.OpenReadAsync(path, 0, Token);
await using var scope = stream.ConfigureAwait(false);
using var reader = new StreamReader(stream, Encoding.UTF8);
return await reader.ReadToEndAsync(Token);
}
}
tests/DodoSSH.Client.Ssh.Tests/SshServerFixture.cs
+63
View File
@@ -29,7 +29,10 @@ public sealed class SshServerFixture : IAsyncLifetime
private const int SshPort = 2222;
private readonly SemaphoreSlim sftpGate = new(1, 1);
private IContainer? container;
private ISftpSession? sftp;
/// <summary>Host port the container's sshd is published on.</summary>
public ushort Port => container!.GetMappedPublicPort(SshPort);
@@ -68,9 +71,69 @@ public sealed class SshServerFixture : IAsyncLifetime
await container.StartAsync();
}
/// <summary>
/// One file-transfer session, opened on first use and shared by every test that wants one.
/// </summary>
/// <remarks>
/// <para>
/// Shared rather than opened per test, and that is a limit of the server rather than an optimisation.
/// sshd's <c>MaxStartups</c> drops connections at random once enough are part-way through a handshake,
/// and this client's first contact with an unknown host is a connection deliberately <em>refused</em> at
/// the host key — so a suite that opened its own session per test made two handshakes per test and
/// pushed the whole assembly over the threshold. What that looks like is unrelated tests failing with
/// "the connection was closed by the remote host", a different few each run.
/// </para>
/// <para>
/// Safe to share because an SFTP session holds no per-test state: every test here works in a directory
/// named after itself. See <c>ISftpSession</c>, which is one channel and is used by one caller at a
/// time.
/// </para>
/// </remarks>
public async ValueTask<ISftpSession> SftpAsync(CancellationToken cancellationToken)
{
await sftpGate.WaitAsync(cancellationToken);
try
{
if (sftp is not null)
{
return sftp;
}
var knownHosts = new InMemoryKnownHostStore();
var factory = new SshNetConnectionFactory(knownHosts);
var request = new SshConnectionRequest(
Host, Port, Username, new SshPasswordCredential(Password));
try
{
// Learned by being refused, which is the only way this client learns a host key.
return sftp = await factory.OpenSftpAsync(request, cancellationToken);
}
catch (SshHostKeyUnknownException unknown)
{
await knownHosts.TrustAsync(unknown.Presentation, cancellationToken);
}
return sftp = await factory.OpenSftpAsync(request, cancellationToken);
}
finally
{
sftpGate.Release();
}
}
/// <inheritdoc />
public async ValueTask DisposeAsync()
{
if (sftp is not null)
{
await sftp.DisposeAsync();
}
sftpGate.Dispose();
if (container is not null)
{
await container.DisposeAsync();