feat(uri): ✨ classify remote schemes and report granular availability

Replace the single REMOTE_SUPPORTED_SCHEMA tuple with purpose-specific
scheme sets (natively-checkable, supported RO-Crate roots, known remote)
and add AvailabilityStatus to distinguish AVAILABLE, UNAVAILABLE,
UNAUTHORIZED and UNCHECKABLE outcomes.

Author: kikkomep

rocrate_validator/utils/uri.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import enum
 import re
 from pathlib import Path
 from typing import Optional, Union
@@ -25,6 +26,15 @@
 logger = logging.getLogger(__name__)
 
 
+class AvailabilityStatus(enum.Enum):
+    """Outcome of a URI availability check."""
+
+    AVAILABLE = "available"
+    UNAVAILABLE = "unavailable"
+    UNAUTHORIZED = "unauthorized"
+    UNCHECKABLE = "uncheckable"
+
+
 # RFC 3986 §3.1: scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
 # Require length >= 2 to disambiguate from Windows drive letters
 # (e.g. ``C:\path``). RFC 3986 allows single-character schemes but no
@@ -67,18 +77,62 @@ def is_external_reference(value: object) -> bool:
 
 
 class URI:
-
-    REMOTE_SUPPORTED_SCHEMA = ('http', 'https', 'ftp')
+    # Schemes that the validator can fetch natively to verify availability.
+    # Anything outside this set is treated as remote but un-checkable.
+    NATIVELY_CHECKABLE_SCHEMES = ("http", "https")
+
+    # Schemes accepted as RO-Crate root URIs (the loading code can only
+    # handle these as crate locations).
+    SUPPORTED_ROCRATE_SCHEMES = ("http", "https", "ftp", "file")
+
+    # Well-known remote schemes commonly used to reference data resources
+    # (used to distinguish "recognized but un-checkable" from "unknown").
+    KNOWN_REMOTE_SCHEMES = (
+        # Web
+        "http",
+        "https",
+        # FTP family
+        "ftp",
+        "ftps",
+        "sftp",
+        # Remote shell / transfer
+        "scp",
+        "ssh",
+        "rsync",
+        # Cloud object stores
+        "s3",
+        "gs",
+        "abfs",
+        "abfss",
+        "wasb",
+        "wasbs",
+        # WebDAV
+        "dav",
+        "davs",
+        # Research / big-data filesystems
+        "irods",
+        "hdfs",
+    )
+
+    # Backwards-compatible alias kept for callers that still inspect it.
+    REMOTE_SUPPORTED_SCHEMA = SUPPORTED_ROCRATE_SCHEMES[:-1]  # http, https, ftp
 
     def __init__(self, uri: Union[str, Path]):
+        if uri is None or (isinstance(uri, str) and not uri.strip()):
+            raise ValueError("Invalid URI: empty value")
         self._uri = uri = str(uri)
         try:
-            # map local path to URI with file scheme
-            if not re.match(r'^\w+://', uri):
+            # Inputs that are not external references are assumed to be local
+            # paths, so the ``file://`` scheme is added explicitly. The
+            # detection covers both authority-based schemes (``http://``,
+            # ``scp://``) and scheme-only ones (``urn:``, ``doi:``), as
+            # defined by RFC 3986.
+            if not is_external_reference(uri):
                 uri = f"file://{uri}"
             # parse the value to extract the scheme
             self._parse_result = urlparse(uri)
-            assert self.scheme in self.REMOTE_SUPPORTED_SCHEMA + ('file',), "Invalid URI scheme"
+            if not self.scheme:
+                raise ValueError("URI has no scheme")
         except Exception as e:
             if logger.isEnabledFor(logging.DEBUG):
                 logger.debug(e)
@@ -127,28 +181,70 @@ def as_path(self) -> Path:
         return Path(self._uri)
 
     def is_remote_resource(self) -> bool:
-        return self.scheme in self.REMOTE_SUPPORTED_SCHEMA
+        """Return True for any well-formed URI whose scheme is not `file`."""
+        return bool(self.scheme) and self.scheme != "file"
 
     def is_local_resource(self) -> bool:
-        return not self.is_remote_resource()
+        return self.scheme == "file"
+
+    def is_natively_checkable(self) -> bool:
+        """Return True if availability can be verified via a native request."""
+        return self.scheme in self.NATIVELY_CHECKABLE_SCHEMES
+
+    def is_known_remote_scheme(self) -> bool:
+        """Return True if the scheme is one of the well-known remote schemes."""
+        return self.scheme in self.KNOWN_REMOTE_SCHEMES
+
+    def has_supported_rocrate_scheme(self) -> bool:
+        """Return True if the scheme is supported as an RO-Crate root URI."""
+        return self.scheme in self.SUPPORTED_ROCRATE_SCHEMES
 
     def is_local_directory(self) -> bool:
         return self.is_local_resource() and self.as_path().is_dir()
 
     def is_local_file(self) -> bool:
         return self.is_local_resource() and self.as_path().is_file()
 
-    def is_available(self) -> bool:
-        """Check if the resource is available"""
+    def check_availability(self) -> AvailabilityStatus:
+        """
+        Inspect the resource availability with as much detail as possible.
+
+        Distinguishes:
+          - AVAILABLE: confirmed reachable
+          - UNAUTHORIZED: reachable but protected (HTTP 401/403)
+          - UNAVAILABLE: confirmed not reachable
+          - UNCHECKABLE: scheme has no native check (e.g. scp://, s3://)
+        """
         if self.is_remote_resource():
+            if not self.is_natively_checkable():
+                logger.debug(
+                    "Cannot natively verify availability for URI '%s' (scheme '%s')",
+                    self._uri,
+                    self.scheme,
+                )
+                return AvailabilityStatus.UNCHECKABLE
             try:
                 response = HttpRequester().head(self._uri, allow_redirects=True)
-                return response.status_code in (200, 302)
+                if response.status_code in (200, 302):
+                    return AvailabilityStatus.AVAILABLE
+                if response.status_code in (401, 403):
+                    return AvailabilityStatus.UNAUTHORIZED
+                return AvailabilityStatus.UNAVAILABLE
             except Exception as e:
                 if logger.isEnabledFor(logging.DEBUG):
                     logger.debug(e)
-                return False
-        return Path(self._uri).exists()
+                return AvailabilityStatus.UNAVAILABLE
+        return AvailabilityStatus.AVAILABLE if Path(self._uri).exists() else AvailabilityStatus.UNAVAILABLE
+
+    def is_available(self) -> bool:
+        """
+        Return True only when the resource is confirmed available.
+
+        Resources that cannot be verified (unsupported scheme, auth-protected)
+        return False here; callers that need to distinguish those cases should
+        use :meth:`check_availability` instead.
+        """
+        return self.check_availability() == AvailabilityStatus.AVAILABLE
 
     def __str__(self):
         return self._uri
@@ -179,6 +275,9 @@ def validate_rocrate_uri(uri: Union[str, Path, URI], silent: bool = False) -> bo
         try:
             # parse the value to extract the scheme
             uri = URI(str(uri)) if isinstance(uri, str) or isinstance(uri, Path) else uri
+            # restrict RO-Crate roots to schemes the loader can actually handle
+            if not uri.has_supported_rocrate_scheme():
+                raise errors.ROCrateInvalidURIError(uri)
             # check if the URI is a remote resource or local directory or local file
             if not uri.is_remote_resource() and not uri.is_local_directory() and not uri.is_local_file():
                 raise errors.ROCrateInvalidURIError(uri)
@@ -187,7 +286,7 @@ def validate_rocrate_uri(uri: Union[str, Path, URI], silent: bool = False) -> bo
                 raise errors.ROCrateInvalidURIError(uri)
             # check if the resource is available
             if not uri.is_available():
-                raise errors.ROCrateInvalidURIError(uri, message=f"The RO-crate at the URI \"{uri}\" is not available")
+                raise errors.ROCrateInvalidURIError(uri, message=f'The RO-crate at the URI "{uri}" is not available')
             return True
         except ValueError as e:
             logger.error(e)