SFTP Integration

[fabio-marini]

**Closes #1057 **

Adds a hosting and client integration for this SFTP server.

PR Checklist

• Created a feature/dev branch in your fork (vs. submitting directly from a commit on main)
• Based off latest main branch of toolkit
• PR doesn't include merge commits (always rebase on top of our main, if needed)
• New integration
  • Docs are written
  • Added description of major feature to project description for NuGet package (4000 total character limit, so don't push entire description over that)
• Tests for the changes have been added (for bug fixes / features) (if applicable)
• Contains NO breaking changes
• Every new API (including internal ones) has full XML docs
• Code follows all style conventions

Other information

[Copilot]

Pull request overview

This PR adds a comprehensive SFTP integration for .NET Aspire, providing both hosting and client capabilities for working with SFTP servers using the atmoz/sftp Docker container and the SSH.NET library.

Key Changes:

• Hosting integration (CommunityToolkit.Aspire.Hosting.Sftp) for running atmoz SFTP containers with support for user configuration, host keys, and public key authentication
• Client integration (CommunityToolkit.Aspire.Sftp) for connecting to SFTP servers with health checks, telemetry, and configuration support
• Complete test coverage including functional tests and unit tests

Reviewed changes

Copilot reviewed 36 out of 37 changed files in this pull request and generated 30 comments.

Show a summary per file

File	Description
src/CommunityToolkit.Aspire.Hosting.Sftp/SftpHostingExtensions.cs	Extension methods for adding SFTP container resources with user files and key management
src/CommunityToolkit.Aspire.Hosting.Sftp/SftpContainerResource.cs	Resource definition with connection string and endpoint properties
src/CommunityToolkit.Aspire.Hosting.Sftp/SftpContainerImageTags.cs	Container image configuration for atmoz/sftp
src/CommunityToolkit.Aspire.Hosting.Sftp/KeyType.cs	Enum defining supported key types (Ed25519, RSA)
src/CommunityToolkit.Aspire.Hosting.Sftp/README.md	Documentation for hosting integration usage
src/CommunityToolkit.Aspire.Sftp/AspireSftpExtensions.cs	Client registration with DI, configuration, and health check setup
src/CommunityToolkit.Aspire.Sftp/SftpSettings.cs	Configuration settings for connection, authentication, health checks, and tracing
src/CommunityToolkit.Aspire.Sftp/SftpHealthCheck.cs	Health check implementation for SFTP connectivity
src/CommunityToolkit.Aspire.Sftp/README.md	Documentation for client integration usage
tests/CommunityToolkit.Aspire.Hosting.Sftp.Tests/SftpFunctionalTests.cs	Functional tests for various SFTP configuration scenarios
tests/CommunityToolkit.Aspire.Hosting.Sftp.Tests/ContainerResourceCreationTests.cs	Unit tests for resource builder validation
tests/CommunityToolkit.Aspire.Hosting.Sftp.Tests/AppHostTests.cs	Integration tests using the example AppHost
tests/CommunityToolkit.Aspire.Sftp.Tests/AspireSftpClientExtensionsTest.cs	Unit tests for client extension methods and configuration
examples/sftp/CommunityToolkit.Aspire.Hosting.Sftp.AppHost/Program.cs	Example AppHost demonstrating SFTP integration
examples/sftp/CommunityToolkit.Aspire.Hosting.Sftp.ApiService/Program.cs	Example API service with upload/download endpoints
Directory.Packages.props	Added SSH.NET and Polly package versions
CommunityToolkit.Aspire.slnx	Added new projects to solution

[fabio-marini]

@dotnet-policy-service agree

[aaronpowell]

Nice looking implementation. Just have a question around the API design and some comments on the tests as we want to ensure they are easy to maintain.

[aaronpowell]

Is the SFTP_USERS always going to be needed when using the hosting integration? If so, is there a way we could wrap it in an API that helps craft the environment variable in the appropriate format to avoid user error?

[fabio-marini]

No, it's not. There are two other ways to supply users to the server: arguments (WithArgs()) and config file (WithUsersFile()). But at least one user is required for the server to start.

All of the above methods use the same format for specifying users and support both clear-text (pass) and encrypted ($5$t9qxNlrcFqVBNnad$U27ZrjbKNjv4JkRWvi6MjX4x6KXNQGr8NTIySOcDgi4:e) passwords.

There's a quick note in the README about generating encrypted passwords using mkpasswd.

I've only added a public API for files so they get mounted in the right place, but it's easy enough to add APIs for WithArgs() and WithEnvironment(), just let me know?

[aaronpowell]

Is there a more specific version tag that we can use to avoid versions being pushed that could introduce behaviour changes we don't anticipate?

[fabio-marini]

Looking at this, only debian, alpine and latest seem to be supported...

I could make it a parameter in the AddSftp() API with a default of latest?

[aaronpowell]

Well... I suppose SFTP is pretty stable so it shouldn't make a huge difference 🤣

[fabio-marini]

Thank you! 😊 I have implemented most of the changes now and left a note about the rest...

[aaronpowell]

Last thing, the tests need to be added to the github actions workflow - there's a script in eng/testing that will do that

[fabio-marini]

Thank you for fixing that conflict for me @aaronpowell. I've increased the retry params for the unit tests, hopefully that'll allow those tests to pass now...