makers-sdk 0.1.0__py3-none-any.whl

makers_sdk/__init__.py

@@ -0,0 +1,26 @@
+# sdk-v1.CONTRACT.6 sdk-v1.CONTRACT.19 sdk-v1.CONTRACT.102
+from .client import Makers
+from .errors import (
+    AuthError,
+    ConflictError,
+    DeploymentTimeoutError,
+    MakersError,
+    NotFoundError,
+    RateLimitError,
+    TimeoutError,
+    UploadError,
+    ValidationError,
+)
+
+__all__ = [
+    "AuthError",
+    "ConflictError",
+    "DeploymentTimeoutError",
+    "Makers",
+    "MakersError",
+    "NotFoundError",
+    "RateLimitError",
+    "TimeoutError",
+    "UploadError",
+    "ValidationError",
+]

makers_sdk/_artifacts.py

@@ -0,0 +1,361 @@
+from __future__ import annotations
+
+import fnmatch
+import os
+import stat
+import tempfile
+import zipfile
+from contextlib import contextmanager
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path, PurePosixPath
+from typing import Any, Iterator, Mapping
+
+from .errors import ValidationError
+
+
+# sdk-v1.CONTRACT.36 sdk-v1.CONTRACT.117 sdk-v1.CONTRACT.128
+# sdk-v1.CONTRACT.130
+_DEFAULT_EXCLUDED_DIRECTORIES = {".git", "node_modules"}
+_DEFAULT_ROOT_EXCLUDED_DIRECTORIES = {".edgeone"}
+_DEFAULT_EXCLUDED_FILES = {".env", ".DS_Store", "Thumbs.db", "desktop.ini"}
+_DEFAULT_EXCLUDED_SUFFIXES = (".log", ".tmp", ".temp", ".swp", ".swo")
+_EDGEONE_DIR = ".edgeone"
+_EDGEONE_CONFIG = "edgeone.json"
+_KEPT_DOT_SEGMENTS = {".well-known", _EDGEONE_DIR}
+
+
+@dataclass(frozen=True)
+class PreparedArtifact:
+    archive_path: Path
+    total_bytes: int
+    total_files: int
+
+
+def _zip_entry_name(info: zipfile.ZipInfo) -> str:
+    return (info.orig_filename or info.filename).split("\x00", 1)[0]
+
+
+def _normalized_path(path: str, *, label: str) -> str:
+    if (
+        not path
+        or "\\" in path
+        or path.startswith("/")
+        or (
+            len(path) >= 2
+            and path[0] in "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+            and path[1] == ":"
+        )
+    ):
+        raise ValidationError(
+            f"{label} paths must be relative POSIX paths: {path}."
+        )
+    parts = PurePosixPath(path).parts
+    if ".." in parts:
+        raise ValidationError(
+            f"{label} paths must not contain parent traversal: {path}."
+        )
+    normalized = "/".join(part for part in parts if part != ".")
+    if not normalized:
+        raise ValidationError(
+            f"{label} paths must be relative POSIX paths: {path}."
+        )
+    return normalized
+
+
+def _excluded_directory_names(is_edgeone_directory: bool) -> set[str]:
+    if is_edgeone_directory:
+        return {".git"}
+    return set(_DEFAULT_EXCLUDED_DIRECTORIES)
+
+
+def _has_ignored_dot_segment(path: str) -> bool:
+    return any(
+        part.startswith(".") and part not in _KEPT_DOT_SEGMENTS
+        for part in PurePosixPath(path).parts
+    )
+
+
+def _is_excluded(
+    path: str, patterns: list[str], *, is_edgeone_directory: bool
+) -> bool:
+    parts = PurePosixPath(path).parts
+    if (
+        not is_edgeone_directory
+        and _has_ignored_dot_segment(path)
+    ):
+        return True
+    if (
+        len(parts) > 1
+        and parts[0] in _DEFAULT_ROOT_EXCLUDED_DIRECTORIES
+    ):
+        return True
+    excluded_directories = _excluded_directory_names(is_edgeone_directory)
+    if any(part in excluded_directories for part in parts[:-1]):
+        return True
+    name = parts[-1]
+    if name in _DEFAULT_EXCLUDED_FILES or name.endswith(
+        _DEFAULT_EXCLUDED_SUFFIXES
+    ):
+        return True
+    return any(_matches_posix_glob(path, pattern) for pattern in patterns)
+
+
+def _matches_posix_glob(path: str, pattern: str) -> bool:
+    path_parts = path.split("/")
+    pattern_parts = pattern.split("/")
+
+    @lru_cache(maxsize=None)
+    def match(path_index: int, pattern_index: int) -> bool:
+        if pattern_index == len(pattern_parts):
+            return path_index == len(path_parts)
+        current = pattern_parts[pattern_index]
+        if current == "**":
+            return match(path_index, pattern_index + 1) or (
+                path_index < len(path_parts)
+                and match(path_index + 1, pattern_index)
+            )
+        return (
+            path_index < len(path_parts)
+            and fnmatch.fnmatchcase(path_parts[path_index], current)
+            and match(path_index + 1, pattern_index + 1)
+        )
+
+    return match(0, 0)
+
+
+def _validate_patterns(patterns: Any) -> list[str]:
+    if patterns is None:
+        return []
+    if not isinstance(patterns, list) or not all(
+        isinstance(pattern, str) for pattern in patterns
+    ):
+        raise ValidationError("exclude_patterns must be a list of POSIX globs.")
+    for pattern in patterns:
+        if (
+            not pattern
+            or "\\" in pattern
+            or pattern.startswith("/")
+            or ".." in PurePosixPath(pattern).parts
+        ):
+            raise ValidationError(
+                "excludePatterns must contain relative POSIX globs."
+            )
+        if pattern.startswith("!"):
+            raise ValidationError(
+                f"excludePatterns does not support negation: {pattern}."
+            )
+    return patterns
+
+
+def _assert_not_symlink(path: Path, relative: str) -> None:
+    if path.is_symlink():
+        raise ValidationError(
+            "Directory artifacts must not contain symbolic links: "
+            f"{relative}."
+        )
+
+
+def _should_descend_directory(
+    path: Path,
+    relative: str,
+    patterns: list[str],
+    *,
+    is_edgeone_directory: bool,
+) -> bool:
+    if _is_excluded(
+        relative, patterns, is_edgeone_directory=is_edgeone_directory
+    ) or _is_excluded(
+        f"{relative}/placeholder",
+        patterns,
+        is_edgeone_directory=is_edgeone_directory,
+    ):
+        return False
+    _assert_not_symlink(path, relative)
+    return True
+
+
+def _directory_entries(
+    directory: Path, patterns: list[str]
+) -> list[tuple[str, Path]]:
+    is_edgeone_directory = directory.name == _EDGEONE_DIR
+    entries: list[tuple[str, Path]] = []
+    for root, directory_names, file_names in os.walk(
+        directory, followlinks=False
+    ):
+        root_path = Path(root)
+        kept_directories: list[str] = []
+        for name in sorted(directory_names):
+            path = root_path / name
+            relative = path.relative_to(directory).as_posix()
+            if _should_descend_directory(
+                path,
+                relative,
+                patterns,
+                is_edgeone_directory=is_edgeone_directory,
+            ):
+                kept_directories.append(name)
+        directory_names[:] = kept_directories
+        for name in sorted(file_names):
+            path = root_path / name
+            relative = path.relative_to(directory).as_posix()
+            if _is_excluded(
+                relative,
+                patterns,
+                is_edgeone_directory=is_edgeone_directory,
+            ):
+                continue
+            _assert_not_symlink(path, relative)
+            entries.append((relative, path))
+    return sorted(entries)
+
+
+def _write_zip(
+    archive_path: Path, entries: list[tuple[str, bytes]]
+) -> PreparedArtifact:
+    with zipfile.ZipFile(
+        archive_path, "w", compression=zipfile.ZIP_DEFLATED
+    ) as archive:
+        for path, content in entries:
+            archive.writestr(path, content)
+    return PreparedArtifact(
+        archive_path=archive_path,
+        total_bytes=sum(len(content) for _, content in entries),
+        total_files=len(entries),
+    )
+
+
+def _validate_archive(archive_path: Path) -> PreparedArtifact:
+    try:
+        with zipfile.ZipFile(archive_path) as archive:
+            seen: set[str] = set()
+            total_bytes = 0
+            total_files = 0
+            for info in archive.infolist():
+                path = _zip_entry_name(info)
+                normalized = _normalized_path(
+                    path, label="Archive entry"
+                ).rstrip("/")
+                if normalized in seen:
+                    raise ValidationError(
+                        "Archive contains a duplicate normalized path: "
+                        f"{normalized}."
+                    )
+                seen.add(normalized)
+                mode = info.external_attr >> 16
+                if stat.S_ISLNK(mode):
+                    raise ValidationError(
+                        "Archive artifacts must not contain symbolic links: "
+                        f"{normalized}."
+                    )
+                if not info.is_dir():
+                    total_bytes += info.file_size
+                    total_files += 1
+            return PreparedArtifact(
+                archive_path=archive_path,
+                total_bytes=total_bytes,
+                total_files=total_files,
+            )
+    except (FileNotFoundError, IsADirectoryError, zipfile.BadZipFile) as error:
+        raise ValidationError(f"Invalid Zip archive: {archive_path}.") from error
+
+
+# sdk-v1.CONTRACT.127
+def _apply_edgeone_cli_layout(
+    directory: Path, entries: list[tuple[str, Path]]
+) -> list[tuple[str, bytes]]:
+    files = [(path, source.read_bytes()) for path, source in entries]
+    if directory.name != _EDGEONE_DIR:
+        return files
+    parent_name = Path(os.path.abspath(os.fspath(directory))).parent.name
+    if not parent_name or parent_name in {".", "/"}:
+        raise ValidationError(
+            "Directory artifact .edgeone must have a named parent directory."
+        )
+    prefix = f"{parent_name}/{_EDGEONE_DIR}"
+    laid_out = [(f"{prefix}/{path}", content) for path, content in files]
+    config = directory.parent / _EDGEONE_CONFIG
+    if config.is_symlink():
+        raise ValidationError(
+            "Directory artifacts must not contain symbolic links: "
+            f"{parent_name}/{_EDGEONE_CONFIG}."
+        )
+    if config.is_file():
+        laid_out.append(
+            (f"{parent_name}/{_EDGEONE_CONFIG}", config.read_bytes())
+        )
+    laid_out.sort(key=lambda item: item[0])
+    return laid_out
+
+
+def _directory_zip_entries(artifact: Mapping[str, Any]) -> list[tuple[str, bytes]]:
+    directory = Path(str(artifact["directory"]))
+    if directory.is_symlink():
+        raise ValidationError(
+            "Directory artifact path must not be a symbolic link."
+        )
+    if not directory.is_dir():
+        raise ValidationError("Directory artifact path must be a directory.")
+    patterns = _validate_patterns(
+        artifact.get("exclude_patterns", artifact.get("excludePatterns"))
+    )
+    return _apply_edgeone_cli_layout(
+        directory, _directory_entries(directory, patterns)
+    )
+
+
+def _inline_file_content(value: Any) -> bytes:
+    if isinstance(value, str):
+        return value.encode()
+    if isinstance(value, bytes):
+        return value
+    raise ValidationError("Inline file contents must be str or bytes.")
+
+
+def _inline_zip_entries(files: Any) -> list[tuple[str, bytes]]:
+    if not isinstance(files, Mapping):
+        raise ValidationError("Artifact files must be a mapping.")
+    seen: set[str] = set()
+    entries: list[tuple[str, bytes]] = []
+    for path, value in files.items():
+        normalized = _normalized_path(str(path), label="Inline file")
+        if normalized in seen:
+            raise ValidationError(
+                "Inline files contain a duplicate normalized path: "
+                f"{normalized}."
+            )
+        seen.add(normalized)
+        entries.append((normalized, _inline_file_content(value)))
+    entries.sort(key=lambda entry: entry[0])
+    return entries
+
+
+# sdk-v1.CONTRACT.8 sdk-v1.CONTRACT.17 sdk-v1.CONTRACT.26
+# sdk-v1.CONTRACT.36 sdk-v1.CONTRACT.37 sdk-v1.CONTRACT.52
+# sdk-v1.CONTRACT.59 sdk-v1.CONTRACT.60 sdk-v1.CONTRACT.61
+# sdk-v1.CONTRACT.90 sdk-v1.CONTRACT.108 sdk-v1.CONTRACT.111
+# sdk-v1.CONTRACT.114 sdk-v1.CONTRACT.117 sdk-v1.CONTRACT.127
+# sdk-v1.CONTRACT.128 sdk-v1.CONTRACT.130
+@contextmanager
+def prepare_artifact(
+    artifact: Mapping[str, Any],
+) -> Iterator[PreparedArtifact]:
+    variants = [name for name in ("directory", "archive", "files") if name in artifact]
+    if len(variants) != 1:
+        raise ValidationError(
+            "Artifact must contain exactly one of directory, archive, or files."
+        )
+
+    variant = variants[0]
+    if variant == "archive":
+        yield _validate_archive(Path(str(artifact["archive"])))
+        return
+
+    with tempfile.TemporaryDirectory(prefix="edgeone-makers-sdk-") as temporary:
+        archive_path = Path(temporary) / "artifact.zip"
+        entries = (
+            _directory_zip_entries(artifact)
+            if variant == "directory"
+            else _inline_zip_entries(artifact["files"])
+        )
+        yield _write_zip(archive_path, entries)