pyspiral 0.3.1__cp310-abi3-macosx_11_0_arm64.whl → 0.4.0__cp310-abi3-macosx_11_0_arm64.whl

spiral/api/client.py

@@ -0,0 +1,160 @@
+import logging
+from collections.abc import Iterable, Iterator, Mapping
+from typing import Any, Generic, TypeVar
+
+import httpx
+from httpx import HTTPStatusError
+from pydantic import BaseModel, Field, TypeAdapter
+
+from spiral.core.client import Authn
+
+log = logging.getLogger(__name__)
+
+
+E = TypeVar("E")
+
+
+class PagedRequest(BaseModel):
+    page_token: str | None = None
+    page_size: int = 50
+
+
+class PagedResponse(BaseModel, Generic[E]):
+    items: list[E] = Field(default_factory=list)
+    next_page_token: str | None = None
+
+
+PagedReqT = TypeVar("PagedReqT", bound=PagedRequest)
+
+
+class Paged(Iterable[E], Generic[E]):
+    def __init__(
+        self,
+        client: "_Client",
+        path: str,
+        page_token: str | None,
+        page_size: int,
+        response_cls: type[PagedResponse[E]],
+        params: Mapping[str, str] | None = None,
+    ):
+        self._client = client
+        self._path = path
+        self._response_cls = response_cls
+
+        self._page_size = page_size
+
+        self._params = params or {}
+        if page_token is not None:
+            self._params["page_token"] = str(page_token)
+        # TODO(marko): Support paging.
+        # if page_size is not None:
+        #     self._params["page_size"] = str(page_size)
+
+        self._response: PagedResponse[E] = client.get(path, response_cls, params=self._params)
+
+    @property
+    def page(self) -> PagedResponse[E]:
+        return self._response
+
+    def __iter__(self) -> Iterator[E]:
+        while True:
+            yield from self._response.items
+
+            if self._response.next_page_token is None:
+                break
+
+            params = self._params.copy()
+            params["page_token"] = self._response.next_page_token
+            self._response = self._client.get(self._path, self._response_cls, params=params)
+
+
+class ServiceBase:
+    def __init__(self, client: "_Client"):
+        self.client = client
+
+
+class SpiralHTTPError(Exception):
+    def __init__(self, body: str, code: int):
+        super().__init__(body)
+        self.body = body
+        self.code = code
+
+
+class _Client:
+    RequestT = TypeVar("RequestT")
+    ResponseT = TypeVar("ResponseT")
+
+    def __init__(self, http: httpx.Client, authn: Authn):
+        self.http = http
+        self.authn = authn
+
+    def get(
+        self, path: str, response_cls: type[ResponseT], *, params: Mapping[str, str | list[str]] | None = None
+    ) -> ResponseT:
+        return self.request("GET", path, None, response_cls, params=params)
+
+    def post(
+        self,
+        path: str,
+        req: RequestT,
+        response_cls: type[ResponseT],
+        *,
+        params: Mapping[str, str | list[str]] | None = None,
+    ) -> ResponseT:
+        return self.request("POST", path, req, response_cls, params=params)
+
+    def put(
+        self,
+        path: str,
+        req: RequestT,
+        response_cls: type[ResponseT],
+        *,
+        params: Mapping[str, str | list[str]] | None = None,
+    ) -> ResponseT:
+        return self.request("PUT", path, req, response_cls, params=params)
+
+    def delete(
+        self, path: str, response_cls: type[ResponseT], *, params: Mapping[str, str | list[str]] | None = None
+    ) -> ResponseT:
+        return self.request("DELETE", path, None, response_cls, params=params)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        req: RequestT | None,
+        response_cls: type[ResponseT],
+        *,
+        params: Mapping[str, str | list[str]] | None = None,
+    ) -> ResponseT:
+        req_data: dict[str, Any] = {}
+        if req is not None:
+            req_data = dict(json=TypeAdapter(req.__class__).dump_python(req, mode="json"))
+
+        token = self.authn.token()
+        resp = self.http.request(
+            method,
+            path,
+            params=params or {},
+            headers={"authorization": f"Bearer {token.expose_secret()}"} if token else None,
+            **req_data,
+        )
+
+        try:
+            resp.raise_for_status()
+        except HTTPStatusError as e:
+            # Enrich the exception with the response body
+            raise SpiralHTTPError(body=resp.text, code=resp.status_code) from e
+
+        return TypeAdapter(response_cls).validate_python(resp.json())
+
+    def paged(
+        self,
+        path: str,
+        response_cls: type[PagedResponse[E]],
+        *,
+        page_token: str | None = None,
+        page_size: int = 50,
+        params: Mapping[str, str] | None = None,
+    ) -> Paged[E]:
+        return Paged(self, path, page_token, page_size, response_cls, params)

spiral/api/filesystems.py

@@ -1,125 +1,153 @@
-from datetime import timedelta
 from enum import Enum
 from typing import Annotated, Literal
 
 from pydantic import AfterValidator, BaseModel, Field
 
-from . import ProjectId, ServiceBase
+from .client import Paged, PagedResponse, ServiceBase
+from .types import ProjectId
+
+
+def _validate_directory_path(path: str) -> str:
+    if not path.startswith("/"):
+        raise ValueError("Directory path must start with a slash.")
+    if not path.endswith("/"):
+        raise ValueError("Directory path must not end with a slash.")
+    return path
+
+
+DirectoryPath = Annotated[str, AfterValidator(_validate_directory_path)]
+FilePath = str  # Path or directory
 
 
 class BuiltinFileSystem(BaseModel):
+    """Spiral supports several builtin file systems in different cloud provider regions."""
+
     type: Literal["builtin"] = "builtin"
     provider: str
 
 
-FileSystem = Annotated[BuiltinFileSystem, Field(discriminator="type")]
+class UpstreamFileSystem(BaseModel):
+    """File system that points to another project, usually a "file system" project.
 
+    Upstream project must have an external file system configured,
+    and not a builtin file system or another upstream file system.
+    """
 
-def _validate_file_path(path: str) -> str:
-    if "//" in path:
-        raise ValueError("FilePath must not contain multiple slashes")
-    if not path.startswith("/"):
-        raise ValueError("FilePath must start with /")
-    if path.endswith("/"):
-        raise ValueError("FilePath must not end with /")
-    return path
+    type: Literal["upstream"] = "upstream"
+    project_id: ProjectId
 
 
-FilePath = Annotated[
-    str,
-    AfterValidator(_validate_file_path),
-    Field(description="A path to an individual file in the file system. Must not end with a slash."),
-]
+class S3FileSystem(BaseModel):
+    """File system backed by an S3-compatible bucket."""
 
+    type: Literal["s3"] = "s3"
+    endpoint: str = "https://s3.amazonaws.com"
+    region: str = "auto"
+    bucket: str
+    directory: DirectoryPath | None
 
-def _validate_prefix(path: str) -> str:
-    if "//" in path:
-        raise ValueError("Prefix must not contain multiple slashes")
-    if not path.startswith("/"):
-        raise ValueError("Prefix must start with /")
-    if not path.endswith("/"):
-        raise ValueError("Prefix must end with /")
-    return path
 
+class GCSFileSystem(BaseModel):
+    """File system backed by a Google Cloud Storage bucket."""
+
+    type: Literal["gcs"] = "gcs"
+    region: str
+    bucket: str
+    directory: DirectoryPath | None
 
-Prefix = Annotated[
-    str,
-    AfterValidator(_validate_prefix),
-    Field(description="A prefix in a file system. Must end with a slash."),
+
+FileSystem = Annotated[
+    BuiltinFileSystem | UpstreamFileSystem | S3FileSystem | GCSFileSystem, Field(discriminator="type")
 ]
 
 
-class Mode(Enum):
+class Mode(str, Enum):
     READ_ONLY = "ro"
     READ_WRITE = "rw"
 
 
 class Mount(BaseModel):
+    """Mount grants permission to a Spiral resource to use a specific directory within the file system."""
+
     id: str
     project_id: ProjectId
-    prefix: Prefix
+    directory: DirectoryPath
     mode: Mode
     principal: str
 
 
-class GetFileSystem:
-    class Request(BaseModel):
-        project_id: ProjectId
+class AWSSecretAccessKey(BaseModel):
+    """AWS secret access key credentials to be used with an S3 file system.
+    The access key must have read/write access to the bucket specified in the file system.
+    """
+
+    access_key_id: str
+    secret_access_key: str
+
+
+class UpdateS3FileSystem(S3FileSystem):
+    credentials: AWSSecretAccessKey
 
-    class Response(BaseModel):
-        file_system: FileSystem
 
+class GCPServiceAccount(BaseModel):
+    """Google Cloud Platform service account credentials to be used with a GCS file system.
+    The service account must have read/write access to the bucket specified in the file system.
+    """
 
-class UpdateFileSystem:
-    class Request(BaseModel):
-        project_id: ProjectId
-        file_system: FileSystem
+    service_account: str
 
-    class Response(BaseModel):
-        file_system: FileSystem
 
+class UpdateGCSFileSystem(GCSFileSystem):
+    credentials: GCPServiceAccount
 
-class ListProviders:
-    class Response(BaseModel):
-        providers: list[str]
+
+UpdateFileSystemRequest = Annotated[
+    BuiltinFileSystem | UpstreamFileSystem | UpdateS3FileSystem | UpdateGCSFileSystem, Field(discriminator="type")
+]
 
 
-class CreateMount:
-    class Request(BaseModel):
-        project_id: ProjectId
-        prefix: Prefix
-        mode: Mode
-        principal: str
+class UpdateFileSystemResponse(BaseModel):
+    file_system: FileSystem
 
-    class Response(BaseModel):
-        mount: Mount
 
+class CreateMountRequest(BaseModel):
+    directory: DirectoryPath
+    mode: Mode
+    principal: str
 
-class CreateMountToken:
-    class Request(BaseModel):
-        mount_id: str
-        mode: Mode
-        path: FilePath | Prefix
-        ttl: int = Field(default_factory=lambda: int(timedelta(hours=1).total_seconds()))
 
-    class Response(BaseModel):
-        token: str
+class CreateMountResponse(BaseModel):
+    mount: Mount
 
 
 class FileSystemService(ServiceBase):
-    def get_file_system(self, request: GetFileSystem.Request) -> GetFileSystem.Response:
-        """Get the file system currently configured for a project."""
-        return self.client.put("/file-system/get", request, GetFileSystem.Response)
+    """Service for file system operations."""
+
+    def list_providers(self) -> list[str]:
+        """List builtin providers."""
+        response = self.client.get("/v1/file-systems/builtin-providers", dict)
+        return response.get("providers", [])
+
+    def update_file_system(self, project_id: ProjectId, request: UpdateFileSystemRequest) -> UpdateFileSystemResponse:
+        """Update project's default file system."""
+        return self.client.post(f"/v1/file-systems/{project_id}", request, UpdateFileSystemResponse)
+
+    def get_file_system(self, project_id: ProjectId) -> FileSystem:
+        """Get project's default file system."""
+        return self.client.get(f"/v1/file-systems/{project_id}", FileSystem)
 
-    def update_file_system(self, request: UpdateFileSystem.Request) -> UpdateFileSystem.Response:
-        """Update the file system for a project."""
-        return self.client.put("/file-system/update", request, UpdateFileSystem.Response)
+    def create_mount(self, project_id: ProjectId, request: CreateMountRequest) -> CreateMountResponse:
+        """Create a mount."""
+        return self.client.post(f"/v1/file-systems/{project_id}/mounts", request, CreateMountResponse)
 
-    def list_providers(self) -> ListProviders.Response:
-        return self.client.put("/file-system/list-providers", None, ListProviders.Response)
+    def list_mounts(self, project_id: ProjectId) -> Paged[Mount]:
+        """List active mounts in project's file system."""
+        return self.client.paged(f"/v1/file-systems/{project_id}/mounts", PagedResponse[Mount])
 
-    def create_mount(self, request: CreateMount.Request) -> CreateMount.Response:
-        return self.client.post("/file-system/create-mount", request, CreateMount.Response)
+    def get_mount(self, mount_id: str) -> Mount:
+        """Get a mount."""
+        return self.client.get(f"/v1/mounts/{mount_id}", Mount)
 
-    def create_mount_token(self, request: CreateMountToken.Request) -> CreateMountToken.Response:
-        return self.client.post("/file-system/mount-token", request, CreateMountToken.Response)
+    def remove_mount(self, mount_id: str) -> None:
+        """Remove mount."""
+        return self.client.delete(f"/v1/mounts/{mount_id}", None)

spiral/api/organizations.py

@@ -1,90 +1,77 @@
 from enum import Enum
 
-from pydantic import BaseModel, EmailStr, Field
+from pydantic import BaseModel
 
-from . import OrganizationId, Paged, PagedRequest, PagedResponse, ServiceBase
+from .client import Paged, PagedResponse, ServiceBase
+from .types import OrgId
 
 
-class OrganizationRole(Enum):
+class OrgRole(str, Enum):
     OWNER = "owner"
     MEMBER = "member"
     GUEST = "guest"
 
 
-class Organization(BaseModel):
-    id: OrganizationId
-    name: str | None = Field(
-        default=None,
-        description="Optional human-readable name for the organization",
-    )
+class Org(BaseModel):
+    id: OrgId
+    name: str | None = None
 
 
-class OrganizationMembership(BaseModel):
-    organization: Organization
-    role: str = Field(description="The user's role in the organization")
+class OrgMembership(BaseModel):
+    user_id: str
+    org: Org
+    role: str
 
 
-class CreateOrganization:
-    class Request(BaseModel):
-        name: str | None = Field(
-            default=None,
-            description="Optional human-readable name for the organization",
-        )
+class CreateOrgRequest(BaseModel):
+    name: str | None = None
 
-    class Response(BaseModel):
-        organization: Organization
 
+class CreateOrgResponse(BaseModel):
+    org: Org
 
-class ListUserMemberships:
-    class Request(PagedRequest):
-        """List the organization memberships of the current user."""
 
-    class Response(PagedResponse[OrganizationMembership]):
-        """The user's organization memberships."""
+class PortalLinkIntent(str, Enum):
+    SSO = "sso"
+    DIRECTORY_SYNC = "directory-sync"
+    AUDIT_LOGS = "audit-logs"
+    LOG_STREAMS = "log-streams"
+    DOMAIN_VERIFICATION = "domain-verification"
 
 
-class PortalLink:
-    class Intent(Enum):
-        SSO = "sso"
-        DIRECTORY = "directory"
-        AUDIT_LOGS = "audit-logs"
-        LOG_STREAMS = "log-streams"
-        DOMAIN_VERIFICATION = "domain-verification"
+class PortalLinkRequest(BaseModel):
+    intent: PortalLinkIntent
 
-    class Request(BaseModel):
-        intent: "PortalLink.Intent"
 
-    class Response(BaseModel):
-        url: str
+class PortalLinkResponse(BaseModel):
+    url: str
 
 
-class InviteUser:
-    class Request(BaseModel):
-        email: EmailStr
-        role: OrganizationRole
-        expires_in_days: int = 7
+class InviteUserRequest(BaseModel):
+    email: str
+    role: OrgRole
+    expires_in_days: int | None = 7
 
-    class Response(BaseModel):
-        invite_id: str
+
+class InviteUserResponse(BaseModel):
+    invite_id: str
 
 
 class OrganizationService(ServiceBase):
-    def create_organization(self, request: CreateOrganization.Request) -> CreateOrganization.Response:
-        """Create a new organization."""
-        return self.client.post("/organization/create", request, CreateOrganization.Response)
+    """Service for organization operations."""
 
-    def list_user_memberships(self) -> Paged[OrganizationMembership]:
-        """List organizations that the user is a member of."""
-        return self.client.paged(
-            "/organization/list-user-memberships",
-            ListUserMemberships.Request(),
-            ListUserMemberships.Response,
-        )
+    def create(self, request: CreateOrgRequest) -> CreateOrgResponse:
+        """Create a new organization."""
+        return self.client.post("/v1/organizations", request, CreateOrgResponse)
 
-    def portal_link(self, request: PortalLink.Request) -> PortalLink.Response:
-        """Get a link to the organization configuration portal."""
-        return self.client.put("/organization/portal-link", request, PortalLink.Response)
+    def list_memberships(self) -> Paged[OrgMembership]:
+        """List organization memberships."""
+        return self.client.paged("/v1/organizations", PagedResponse[OrgMembership])
 
-    def invite_user(self, request: InviteUser.Request) -> InviteUser.Response:
+    def invite_user(self, request: InviteUserRequest) -> InviteUserResponse:
         """Invite a user to the organization."""
-        return self.client.post("/organization/invite-user", request, InviteUser.Response)
+        return self.client.post("/v1/organizations/invite-user", request, InviteUserResponse)
+
+    def portal_link(self, request: PortalLinkRequest) -> PortalLinkResponse:
+        """Get configuration portal link for the organization."""
+        return self.client.put("/v1/organizations/portal-link", request, PortalLinkResponse)