Merge pull request #22 from LIM-AeroCloud/rel/0.2.0

pb866 · web-flow · commit dc6ddf6e672a · 2025-08-22T00:20:52.000+02:00
Rel/0.2.0
diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
@@ -31,7 +31,7 @@ jobs:
         arch:
           - x64
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: julia-actions/setup-julia@v2
         with:
           version: ${{ matrix.version }}
@@ -53,7 +53,7 @@ jobs:
       contents: write
       statuses: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: julia-actions/setup-julia@v2
         with:
           version: '1'
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,6 +3,26 @@
 This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 The format of the release notes follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [v0.2.0] - 2025-08-22
+
+### Changed
+
+- Added Enum `ErrorCode` for revised error handling with updated error codes ([#21])
+- Invalid paths give an `Base.IOError` during instatiation of an `SFTP.Client`
+- `pwd(::SFTP.Client)`: no validity checks of uri path. This should be done during instantiation
+  of the `SFTP.Client` ([#22])
+
+### Removed
+
+- `pwd(::URI)`, `splitdir(uri::URI, path::AbstractString=".")`, and
+  `basename(uri::URI, path::AbstractString=".")`: only methods with `SFTP.Client` allowed
+  to avoid type piracy ([#22])
+
+### Fixed
+
+- Link targets are displayed as absolute paths again. This bug was introduced after switching
+  internally from split to URIs.splitpath, which does not consider root folders ([#18]).
+
 ## [v0.1.2] - 2025-05-31
 
 ### Deprecated
@@ -109,8 +129,12 @@ All changes for this released are documented in respect to this version.
 [v0.1.0]: https://github.com/LIM-AeroCloud/SFTP.jl/releases/tag/v0.1.0
 [v0.1.1]: https://github.com/LIM-AeroCloud/SFTP.jl/releases/tag/v0.1.1
 [v0.1.2]: https://github.com/LIM-AeroCloud/SFTP.jl/releases/tag/v0.1.2
+[v0.2.0]: https://github.com/LIM-AeroCloud/SFTP.jl/releases/tag/v0.2.0
 [#8]: https://github.com/LIM-AeroCloud/SFTP.jl/issues/8
 [#9]: https://github.com/LIM-AeroCloud/SFTP.jl/issues/9
 [#10]: https://github.com/LIM-AeroCloud/SFTP.jl/issues/10
 [#13]: https://github.com/LIM-AeroCloud/SFTP.jl/issues/13
 [#14]: https://github.com/LIM-AeroCloud/SFTP.jl/issues/14
+[#18]: https://github.com/LIM-AeroCloud/SFTP.jl/issues/18
+[#21]: https://github.com/LIM-AeroCloud/SFTP.jl/issues/21
+[#22]: https://github.com/LIM-AeroCloud/SFTP.jl/issues/22
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "SFTP"
 uuid = "f44f501d-421f-4286-bfa3-132bd4e9b35e"
 authors = ["Peter Bräuer <pb866.git@gmail.com>"]
-version = "0.1.2"
+version = "0.2.0"
 
 [deps]
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
diff --git a/docs/make.jl b/docs/make.jl
@@ -23,6 +23,7 @@ makedocs(
         "Home" => "index.md",
         "Server" => "server.md",
         "Filesystem" => "filesystem.md",
+        "Error handling" => "error.md",
         "Troubleshooting" => "troubleshooting.md",
         "Release notes" => "release-notes.md",
         "Index" => "register.md"
diff --git a/docs/src/error.md b/docs/src/error.md
@@ -0,0 +1,9 @@
+# Error handling
+
+__SFTP.jl__ handles multiple errors related to server access and file structure on the remote
+system. Error codes are defined by the [`ErrorCode`](@ref SFTP.ErrorCode) enum and used as
+error code in `Base.IOError`.
+
+```@docs
+SFTP.ErrorCode
+```
diff --git a/docs/src/filesystem.md b/docs/src/filesystem.md
@@ -17,10 +17,6 @@ for more details on the `URI` struct.
 
 ## Navigating server paths
 
-!!! warning "Deprecation warning"
-    The [`pwd`](@ref) method for `URI` structs will be deprecated in v0.2.0 and
-    replaced by and internal `cwd` method to avoid type piracy.
-
 ```@docs
 pwd
 cd(::SFTP.Client, ::AbstractString)
@@ -34,10 +30,6 @@ walkdir(::SFTP.Client, ::AbstractString; kwargs...)
 
 ## Analyse and manipulate server paths
 
-!!! warning "Deprecation warning"
-    All methods using `URI` instead of [`SFTP.Client`](@ref) in [`basename`](@ref)
-    and [`splitdir`](@ref) will be deprecated in v0.2.0 to avoid type piracy.
-
 !!! warning "Known issue"
     [URIs'](https://github.com/JuliaWeb/URIs.jl.git) `joinpath` method currently
     assigns two leading slashes (`//`) instead of one, if an absolute path is assigned
diff --git a/docs/src/release-notes.md b/docs/src/release-notes.md
@@ -7,6 +7,26 @@ EditURL = "https://github.com/LIM-AeroCloud/SFTP.jl/blob/master/CHANGELOG.md"
 This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 The format of the release notes follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [v0.2.0](https://github.com/LIM-AeroCloud/SFTP.jl/releases/tag/v0.2.0) - 2025-08-22
+
+### Changed
+
+- Added Enum `ErrorCode` for revised error handling with updated error codes ([#21](https://github.com/LIM-AeroCloud/SFTP.jl/issues/21))
+- Invalid paths give an `Base.IOError` during instatiation of an `SFTP.Client`
+- `pwd(::SFTP.Client)`: no validity checks of uri path. This should be done during instantiation
+  of the `SFTP.Client` ([#22](https://github.com/LIM-AeroCloud/SFTP.jl/issues/22))
+
+### Removed
+
+- `pwd(::URI)`, `splitdir(uri::URI, path::AbstractString=".")`, and
+  `basename(uri::URI, path::AbstractString=".")`: only methods with `SFTP.Client` allowed
+  to avoid type piracy ([#22](https://github.com/LIM-AeroCloud/SFTP.jl/issues/22))
+
+### Fixed
+
+- Link targets are displayed as absolute paths again. This bug was introduced after switching
+  internally from split to URIs.splitpath, which does not consider root folders ([#18](https://github.com/LIM-AeroCloud/SFTP.jl/issues/18)).
+
 ## [v0.1.2](https://github.com/LIM-AeroCloud/SFTP.jl/releases/tag/v0.1.2) - 2025-05-31
 
 ### Deprecated
diff --git a/src/SFTP.jl b/src/SFTP.jl
@@ -1,5 +1,46 @@
 module SFTP
 
+# Error Codes for Error Handling of IO Errors
+"""
+# Enum `ErrorCode`
+
+Error codes for SFTP connection and remote filesystem errors:
+
+    EC_INSTANTIATION_ERROR = -1
+    EC_NOERROR = 0
+    EC_ACCESS_DENIED = 1
+    EC_NOT_A_FILE = 2
+    EC_NOT_A_DIR = 3
+    EC_NOT_A_PATH = 4
+    EC_FILE_NOT_FOUND = 5
+    EC_DIR_NOT_FOUND = 6
+    EC_PATH_NOT_FOUND = 7
+    EC_FILE_EXISTS = 8
+    EC_DIR_EXISTS = 9
+    EC_PATH_EXISTS = 10
+    EC_NONEMPTY_DIR = 11
+    EC_BROKEN_LINK = 12
+    EC_INVALID_SCAN = 13
+"""
+@enum ErrorCode begin
+    EC_INSTANTIATION_ERROR = -1
+    EC_NOERROR = 0
+    EC_ACCESS_DENIED = 1
+    EC_NOT_A_FILE = 2
+    EC_NOT_A_DIR = 3
+    EC_NOT_A_PATH = 4
+    EC_FILE_NOT_FOUND = 5
+    EC_DIR_NOT_FOUND = 6
+    EC_PATH_NOT_FOUND = 7
+    EC_FILE_EXISTS = 8
+    EC_DIR_EXISTS = 9
+    EC_PATH_EXISTS = 10
+    EC_NONEMPTY_DIR = 11
+    EC_BROKEN_LINK = 12
+    EC_INVALID_SCAN = 13
+end
+
+# Package imports
 import Downloads
 import LibCURL
 import URIs
@@ -8,12 +49,16 @@ import Logging
 import Downloads: Downloader, Curl.Easy
 import URIs: URI
 
+# Curl error codes
+const CURLE_REMOTE_ACCESS_DENIED = 9
+
+# File includes
 include("client.jl")
 include("fileexchange.jl")
 include("filestats.jl")
 include("filesystem.jl")
-include("deprecated.jl")
 
+# Define API and export structs and functions
 @static if VERSION ≥ v"1.11"
     eval(Meta.parse("public Client, StatStruct, download, stat, filemode, ispath, isdir, isfile, islink, pwd, cd, mv, rm, mkdir, mkpath, readdir, walkdir, joinpath, splitdir, dirname, basename"))
 end
diff --git a/src/client.jl b/src/client.jl
@@ -69,6 +69,22 @@ mutable struct Client
     verbose::Bool
     public_key_file::String
     private_key_file::String
+
+    function Client(
+        downloader::Downloader,
+        uri::URI,
+        username::String,
+        password::String,
+        disable_verify_peer::Bool,
+        disable_verify_host::Bool,
+        verbose::Bool,
+        public_key_file::String,
+        private_key_file::String
+    )::Client
+        client = new(downloader, uri, username, password, disable_verify_peer, disable_verify_host, verbose, public_key_file, private_key_file)
+        ispath(client, client.uri.path) || throw(Base.IOError("Cannot instantiate client; check user credentials and given uri path", Integer(EC_INSTANTIATION_ERROR)))
+        return client
+    end
 end
 
 
@@ -114,6 +130,7 @@ struct StatStruct
             if length(linkparts) == 2
                 desc = linkparts[1]
                 path = URIs.splitpath(linkparts[2])
+                startswith(linkparts[2], "/") && pushfirst!(path, "") # ISSUE: URIs omits root slash in splitpath
                 path = join(path[1:end - 1], "/")
                 root *= " -> " * path
             end
@@ -181,7 +198,7 @@ end
 
 ## Overload Base functions
 
-Base.show(io::IO, sftp::Client)::Nothing =  println(io, "SFTP.Client(\"$(sftp.username)@$(sftp.uri.host)\")")
+Base.show(io::IO, sftp::Client)::Nothing = println(io, "SFTP.Client(\"$(sftp.username)@$(sftp.uri.host)\")")
 
 Base.broadcastable(sftp::Client) = Ref(sftp)
 
@@ -341,7 +358,7 @@ function findbase(stats::Vector{StatStruct}, base::AbstractString, path::Abstrac
     i = findfirst(isequal(base), pathnames)
     # Exception handling, if path is not found
     if isnothing(i)
-        throw(Base.IOError("$path does not exist", -1))
+        throw(Base.IOError("$path does not exist", Integer(EC_INVALID_SCAN)))
     end
     # Return index of base in stats
     return i
diff --git a/src/deprecated.jl b/src/deprecated.jl
diff --git a/src/fileexchange.jl b/src/fileexchange.jl
@@ -51,7 +51,7 @@ function upload(
     #* Check remote and local path
     src = realpath(src)
     dst = joinpath(sftp, dst, "").path
-    isdir(sftp, dst) || throw(Base.IOError("$dst must be a directory", 1))
+    isdir(sftp, dst) || throw(Base.IOError("$dst must be a directory", Integer(EC_NOT_A_DIR)))
     path, base = splitdir(src)
     # Get conflicts with dst
     conflicts = readdir(sftp, dst, __test__)
@@ -135,7 +135,7 @@ function Base.download(
 )::String
     #* Check remote and local path
     base = basename(sftp, src)
-    isdir(dst) || throw(Base.IOError("$dst must be an existing directory", 1))
+    isdir(dst) || throw(Base.IOError("$dst must be an existing directory", Integer(EC_DIR_NOT_FOUND)))
     dst = realpath(dst)
     # Optionally, skip hidden
     ignore_hidden && startswith(base, hide_identifier) && return dst
@@ -198,7 +198,7 @@ array = download(fread, sftp, "data/matrix.csv")
 function Base.download(fcn::Function, sftp::Client, src::AbstractString)
     mktempdir() do path
         # Check if src is a file
-        isfile(sftp, src) || throw(Base.IOError("$src must be an existing file", 1))
+        isfile(sftp, src) || throw(Base.IOError("$src must be an existing file", Integer(EC_FILE_NOT_FOUND)))
         # Download file to temporary directory and return contents with help of fcn
         file = joinpath(path, basename(src))
         file = Downloads.download(string(change_uripath(sftp.uri, src, trailing_slash = false)),
@@ -327,7 +327,7 @@ function upload_file(
     ignore_hidden && filter!(!startswith(hide_identifier), files)
     if isnothing(force)
         !isempty(conflicts) && throw(Base.IOError("cannot overwrite existing path(s) \
-            $(join(joinpath.(sftp, dst, files) .|> cwd, ", ", " and "))", -1))
+            $(join(joinpath.(sftp, dst, files) .|> cwd, ", ", " and "))", Integer(EC_PATH_EXISTS)))
     elseif istrue(force)
         if isempty(__test__)
             rm.(sftp, joinpath.(sftp, dst, conflicts) .|> cwd,
@@ -404,7 +404,7 @@ function download_file(
     #* Prepare local and remote files
     if isnothing(force)
         !isempty(conflicts) && throw(Base.IOError("cannot overwrite existing path(s) \
-            $(join(joinpath.(dst, files), ", ", " and "))", -1))
+            $(join(joinpath.(dst, files), ", ", " and "))", Integer(EC_PATH_EXISTS)))
     elseif istrue(force)
         rm.(normpath.(joinpath.(dst, conflicts)), recursive = true, force = true)
     else
diff --git a/src/filesystem.jl b/src/filesystem.jl
diff --git a/test/deprecated.jl b/test/deprecated.jl
diff --git a/test/runtests.jl b/test/runtests.jl
