loopix-sdk 2.30.0__py3-none-any.whl

loopix/template/readycmd.py

@@ -0,0 +1,144 @@
+import shlex
+
+
+class ReadyCmd:
+    """
+    Wrapper class for ready check commands.
+    """
+
+    def __init__(self, cmd: str):
+        self.__cmd = cmd
+
+    def get_cmd(self):
+        return self.__cmd
+
+
+def wait_for_port(port: int):
+    """
+    Wait for a port to be listening.
+
+    Uses `ss` command to check if a port is open and listening.
+
+    :param port: Port number to wait for
+
+    :return: ReadyCmd that checks for the port
+
+    Example
+    ```python
+    from loopix import Template, wait_for_port
+
+    template = (
+        Template()
+        .from_python_image()
+        .set_start_cmd('python -m http.server 8000', wait_for_port(8000))
+    )
+    ```
+    """
+    # Match the exact listening port via ss's source-port filter (so e.g. port
+    # 80 doesn't match 8080). ss exits 0 regardless of matches, so test for
+    # non-empty output to signal readiness.
+    cmd = f'[ -n "$(ss -Htuln sport = :{port})" ]'
+    return ReadyCmd(cmd)
+
+
+def wait_for_url(url: str, status_code: int = 200):
+    """
+    Wait for a URL to return a specific HTTP status code.
+
+    Uses `curl` to make HTTP requests and check the response status.
+
+    :param url: URL to check (e.g., 'http://localhost:3000/health')
+    :param status_code: Expected HTTP status code (default: 200)
+
+    :return: ReadyCmd that checks the URL
+
+    Example
+    ```python
+    from loopix import Template, wait_for_url
+
+    template = (
+        Template()
+        .from_node_image()
+        .set_start_cmd('npm start', wait_for_url('http://localhost:3000/health'))
+    )
+    ```
+    """
+    cmd = f'curl -s -o /dev/null -w "%{{http_code}}" {shlex.quote(url)} | grep -q "{status_code}"'
+    return ReadyCmd(cmd)
+
+
+def wait_for_process(process_name: str):
+    """
+    Wait for a process with a specific name to be running.
+
+    Uses `pgrep` to check if a process exists.
+
+    :param process_name: Name of the process to wait for
+
+    :return: ReadyCmd that checks for the process
+
+    Example
+    ```python
+    from loopix import Template, wait_for_process
+
+    template = (
+        Template()
+        .from_base_image()
+        .set_start_cmd('./my-daemon', wait_for_process('my-daemon'))
+    )
+    ```
+    """
+    cmd = f"pgrep {shlex.quote(process_name)} > /dev/null"
+    return ReadyCmd(cmd)
+
+
+def wait_for_file(filename: str):
+    """
+    Wait for a file to exist.
+
+    Uses shell test command to check file existence.
+
+    :param filename: Path to the file to wait for
+
+    :return: ReadyCmd that checks for the file
+
+    Example
+    ```python
+    from loopix import Template, wait_for_file
+
+    template = (
+        Template()
+        .from_base_image()
+        .set_start_cmd('./init.sh', wait_for_file('/tmp/ready'))
+    )
+    ```
+    """
+    cmd = f"[ -f {shlex.quote(filename)} ]"
+    return ReadyCmd(cmd)
+
+
+def wait_for_timeout(timeout: int):
+    """
+    Wait for a specified timeout before considering the sandbox ready.
+
+    Uses `sleep` command to wait for a fixed duration.
+
+    :param timeout: Time to wait in **milliseconds** (minimum: 1000ms / 1 second)
+
+    :return: ReadyCmd that waits for the specified duration
+
+    Example
+    ```python
+    from loopix import Template, wait_for_timeout
+
+    template = (
+        Template()
+        .from_node_image()
+        .set_start_cmd('npm start', wait_for_timeout(5000))  # Wait 5 seconds
+    )
+    ```
+    """
+    # convert to seconds, but ensure minimum of 1 second
+    seconds = max(1, timeout // 1000)
+    cmd = f"sleep {seconds}"
+    return ReadyCmd(cmd)

loopix/template/types.py

@@ -0,0 +1,194 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import List, Literal, Optional, TypedDict, Union
+
+from typing_extensions import NotRequired
+
+from loopix.template.logger import LogEntry
+
+
+class TemplateBuildStatus(str, Enum):
+    """
+    Status of a template build.
+    """
+
+    BUILDING = "building"
+    WAITING = "waiting"
+    READY = "ready"
+    ERROR = "error"
+
+
+@dataclass
+class BuildStatusReason:
+    """
+    Reason for the current build status (typically for errors).
+    """
+
+    message: str
+    """Message with the status reason."""
+
+    step: Optional[str] = None
+    """Step that failed."""
+
+    log_entries: List[LogEntry] = field(default_factory=list)
+    """Log entries related to the status reason."""
+
+
+@dataclass
+class TemplateBuildStatusResponse:
+    """
+    Response from getting build status.
+    """
+
+    build_id: str
+    """Build identifier."""
+
+    template_id: str
+    """Template identifier."""
+
+    status: TemplateBuildStatus
+    """Current status of the build."""
+
+    log_entries: List[LogEntry]
+    """Build log entries."""
+
+    logs: List[str]
+    """Build logs (raw strings). Deprecated: use log_entries instead."""
+
+    reason: Optional[BuildStatusReason] = None
+    """Reason for the current status (typically for errors)."""
+
+
+@dataclass
+class TemplateTagInfo:
+    """
+    Information about assigned template tags.
+    """
+
+    build_id: str
+    """Build identifier associated with this tag."""
+
+    tags: List[str]
+    """Assigned tags of the template."""
+
+
+@dataclass
+class TemplateTag:
+    """
+    Detailed information about a single template tag.
+    """
+
+    tag: str
+    """Name of the tag."""
+
+    build_id: str
+    """Build identifier associated with this tag."""
+
+    created_at: datetime
+    """When this tag was assigned."""
+
+
+class InstructionType(str, Enum):
+    """
+    Types of instructions that can be used in a template.
+    """
+
+    COPY = "COPY"
+    ENV = "ENV"
+    RUN = "RUN"
+    WORKDIR = "WORKDIR"
+    USER = "USER"
+
+
+class CopyItem(TypedDict):
+    """
+    Configuration for a single file/directory copy operation.
+    """
+
+    src: Union[Union[str, Path], List[Union[str, Path]]]
+    dest: Union[str, Path]
+    forceUpload: NotRequired[Optional[Literal[True]]]
+    user: NotRequired[Optional[str]]
+    mode: NotRequired[Optional[int]]
+    resolveSymlinks: NotRequired[Optional[bool]]
+    gzip: NotRequired[Optional[bool]]
+
+
+class Instruction(TypedDict):
+    """
+    Represents a single instruction in the template build process.
+    """
+
+    type: InstructionType
+    args: List[str]
+    force: bool
+    forceUpload: NotRequired[Optional[Literal[True]]]
+    filesHash: NotRequired[Optional[str]]
+    resolveSymlinks: NotRequired[Optional[bool]]
+    gzip: NotRequired[Optional[bool]]
+
+
+class GenericDockerRegistry(TypedDict):
+    """
+    Configuration for a generic Docker registry with basic authentication.
+    """
+
+    type: Literal["registry"]
+    username: str
+    password: str
+
+
+class AWSRegistry(TypedDict):
+    """
+    Configuration for AWS Elastic Container Registry (ECR).
+    """
+
+    type: Literal["aws"]
+    awsAccessKeyId: str
+    awsSecretAccessKey: str
+    awsRegion: str
+
+
+class GCPRegistry(TypedDict):
+    """
+    Configuration for Google Container Registry (GCR) or Artifact Registry.
+    """
+
+    type: Literal["gcp"]
+    serviceAccountJson: str
+
+
+"""
+Union type for all supported container registry configurations.
+"""
+RegistryConfig = Union[GenericDockerRegistry, AWSRegistry, GCPRegistry]
+
+
+class TemplateType(TypedDict):
+    """
+    Internal representation of a template for the Loopix build API.
+    """
+
+    fromImage: NotRequired[str]
+    fromTemplate: NotRequired[str]
+    fromImageRegistry: NotRequired[RegistryConfig]
+    startCmd: NotRequired[str]
+    readyCmd: NotRequired[str]
+    steps: List[Instruction]
+    force: bool
+
+
+@dataclass
+class BuildInfo:
+    """
+    Information about a built template.
+    """
+
+    template_id: str
+    build_id: str
+    name: str
+    # Deprecated: use name instead
+    alias: str
+    tags: List[str] = field(default_factory=list)