evserver 0.1.0__tar.gz → 0.3.0__tar.gz

evserver-0.3.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.3
+Name: evserver
+Version: 0.3.0
+Summary: Add your description here
+Author: Wannes Vantorre
+Author-email: Wannes Vantorre <vantorrewannes@gmail.com>
+Requires-Dist: aiofiles>=25.1.0
+Requires-Dist: dill>=0.4.1
+Requires-Dist: fastapi[standard]>=0.140.7
+Requires-Dist: pydantic>=2.13.4
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# Easysnapshot
+
+### Goals
+
+- **Many Archives:** Store in many archives at once.
+- **Emergent Complexity:** Small implementation surface with reasonable usage requirements.
+
+## Client
+
+Clients gather and send information to archive endpoints.
+
+### Commands
+
+- All commands accept `--help` / `-h`.
+- All commands accept `--verbose` / `-v`.
+- **`ev archive register <archive:URL> [user:ID]`:** Claim a specific User ID on the given archive. User ID is random if omitted.
+- **`ev archive unregister <archive:URL> <user:ID>`:** Requests the archive to forget this User ID.
+- **`ev archive login <archive:URL> <user:ID> [workspace:PATH]`:** Sets this combination of Archive URL + User ID as active for this workspace.
+- **`ev archive logout <archive:URL> <user:ID> [workspace:PATH]`:** Sets this combination of Archive URL + User ID as unactive for this workspace.
+- **`ev save <--note <note:TEXT> | -n <note:TEXT> [workspace:PATH]`:** Save the workspace's current state as a new Snapshot, with the note when provided.
+- **`ev list [workspace:PATH]`:** List the Workspace's Snapshots. Also showing notes where set.
+- **`ev clone <source:PATH> <target:PATH> [--snapshot <snapshot:ID> | -s <snapshot:ID>]`:** Clone the source Workspace to the target path, which may not exist yet. Clone the current workspace state if omitted.
+- **`ev forget {--snapshot <snapshot:ID> | -v <snapshot:ID> | --all | -a} [workspace:PATH]`:** Forget the specified snapshot(s) for the given Workspace.
+
+## Archive
+
+Clients recieve and save information from clients through their URL.
+
+### Types
+
+Five distinct types, forming one chain from workspace to content:
+
+| Type        | Contents                                |
+| ----------- | --------------------------------------- |
+| `user`      | Metadata about the user account         |
+| `workspace` | An array of snapshot hashes             |
+| `snapshot`  | A manifest hash and an optional note    |
+| `manifest`  | An array of reference hashes            |
+| `reference` | A relative file path and a content hash |
+| `content`   | Raw byte data                           |
+
+### Endpoints
+
+- **`HEAD /type/<type:ID>`:** Check whether the Type ID already exists.
+- **`GET /type/<type:ID>`:** Returns an object with the Type's data.
+- **`PUT /type/<type:ID>`:** Sets the object with the Type's data.
+- **`DELETE /type/<type:ID>`:** Forget the given Type ID.
+
+### Invariants
+
+- All in workspace configuration, will be done under `./ev` in the workspace root.
+- Archive URL + User ID login configurations are unique per workspace.

evserver-0.3.0/README.md

@@ -0,0 +1,52 @@
+# Easysnapshot
+
+### Goals
+
+- **Many Archives:** Store in many archives at once.
+- **Emergent Complexity:** Small implementation surface with reasonable usage requirements.
+
+## Client
+
+Clients gather and send information to archive endpoints.
+
+### Commands
+
+- All commands accept `--help` / `-h`.
+- All commands accept `--verbose` / `-v`.
+- **`ev archive register <archive:URL> [user:ID]`:** Claim a specific User ID on the given archive. User ID is random if omitted.
+- **`ev archive unregister <archive:URL> <user:ID>`:** Requests the archive to forget this User ID.
+- **`ev archive login <archive:URL> <user:ID> [workspace:PATH]`:** Sets this combination of Archive URL + User ID as active for this workspace.
+- **`ev archive logout <archive:URL> <user:ID> [workspace:PATH]`:** Sets this combination of Archive URL + User ID as unactive for this workspace.
+- **`ev save <--note <note:TEXT> | -n <note:TEXT> [workspace:PATH]`:** Save the workspace's current state as a new Snapshot, with the note when provided.
+- **`ev list [workspace:PATH]`:** List the Workspace's Snapshots. Also showing notes where set.
+- **`ev clone <source:PATH> <target:PATH> [--snapshot <snapshot:ID> | -s <snapshot:ID>]`:** Clone the source Workspace to the target path, which may not exist yet. Clone the current workspace state if omitted.
+- **`ev forget {--snapshot <snapshot:ID> | -v <snapshot:ID> | --all | -a} [workspace:PATH]`:** Forget the specified snapshot(s) for the given Workspace.
+
+## Archive
+
+Clients recieve and save information from clients through their URL.
+
+### Types
+
+Five distinct types, forming one chain from workspace to content:
+
+| Type        | Contents                                |
+| ----------- | --------------------------------------- |
+| `user`      | Metadata about the user account         |
+| `workspace` | An array of snapshot hashes             |
+| `snapshot`  | A manifest hash and an optional note    |
+| `manifest`  | An array of reference hashes            |
+| `reference` | A relative file path and a content hash |
+| `content`   | Raw byte data                           |
+
+### Endpoints
+
+- **`HEAD /type/<type:ID>`:** Check whether the Type ID already exists.
+- **`GET /type/<type:ID>`:** Returns an object with the Type's data.
+- **`PUT /type/<type:ID>`:** Sets the object with the Type's data.
+- **`DELETE /type/<type:ID>`:** Forget the given Type ID.
+
+### Invariants
+
+- All in workspace configuration, will be done under `./ev` in the workspace root.
+- Archive URL + User ID login configurations are unique per workspace.

evserver-0.3.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "evserver"
+version = "0.3.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "aiofiles>=25.1.0",
+    "dill>=0.4.1",
+    "fastapi[standard]>=0.140.7",
+    "pydantic>=2.13.4",
+]
+
+[[project.authors]]
+name = "Wannes Vantorre"
+email = "vantorrewannes@gmail.com"
+
+[project.scripts]
+evserver = "evserver:main"
+
+[build-system]
+requires = ["uv_build>=0.11.32,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "D203",
+    "D213",
+    "COM812",
+    "ISC001",
+    "CPY001",
+    "D419",
+    "D100",
+    "D101",
+    "D102",
+    "D103",
+    "D104",
+    "D107",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101"]
+"tests/unit/**" = ["SLF001"]

evserver-0.1.0/pyproject.toml → evserver-0.3.0/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "evserver"
-version = "0.1.0"
+version = "0.3.0"
 description = "Add your description here"
 readme = "README.md"
 authors = [
@@ -9,7 +9,6 @@ authors = [
 requires-python = ">=3.14"
 dependencies = [
     "aiofiles>=25.1.0",
-    "blake3>=1.0.9",
     "dill>=0.4.1",
     "fastapi[standard]>=0.140.7",
     "pydantic>=2.13.4",

evserver-0.3.0/src/evserver/__init__.py

@@ -0,0 +1,351 @@
+from collections.abc import AsyncGenerator  # noqa: TC003
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Annotated, TypedDict
+
+import dill
+import uvicorn
+from fastapi import Depends, FastAPI, HTTPException, Request, Response
+
+from evserver.stores import DirectoryStore
+from evserver.types import (
+    Content,
+    ContentId,
+    Manifest,
+    ManifestId,
+    Reference,
+    ReferenceId,
+    Snapshot,
+    SnapshotId,
+    User,
+    UserId,
+    Workspace,
+    WorkspaceId,
+)
+
+
+class State(TypedDict):
+    user_store: DirectoryStore[UserId, User]
+    workspace_store: DirectoryStore[WorkspaceId, Workspace]
+    snapshot_store: DirectoryStore[SnapshotId, Snapshot]
+    manifest_store: DirectoryStore[ManifestId, Manifest]
+    reference_store: DirectoryStore[ReferenceId, Reference]
+    content_store: DirectoryStore[ContentId, Content]
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI) -> AsyncGenerator[State]:
+    root_path = Path("data")
+    user_store = DirectoryStore[UserId, User](root_path / "users")
+    workspace_store = DirectoryStore[WorkspaceId, Workspace](root_path / "workspaces")
+    snapshot_store = DirectoryStore[SnapshotId, Snapshot](root_path / "snapshots")
+    manifest_store = DirectoryStore[ManifestId, Manifest](root_path / "manifests")
+    reference_store = DirectoryStore[ReferenceId, Reference](root_path / "references")
+    content_store = DirectoryStore[ContentId, Content](root_path / "contents")
+    yield State(
+        user_store=user_store,
+        workspace_store=workspace_store,
+        snapshot_store=snapshot_store,
+        manifest_store=manifest_store,
+        reference_store=reference_store,
+        content_store=content_store,
+    )
+
+
+application = FastAPI(lifespan=lifespan)
+
+
+def get_user_store(request: Request) -> DirectoryStore[UserId, User]:
+    return request.state.user_store
+
+
+def get_workspace_store(request: Request) -> DirectoryStore[WorkspaceId, Workspace]:
+    return request.state.workspace_store
+
+
+def get_snapshot_store(request: Request) -> DirectoryStore[SnapshotId, Snapshot]:
+    return request.state.snapshot_store
+
+
+def get_manifest_store(request: Request) -> DirectoryStore[ManifestId, Manifest]:
+    return request.state.manifest_store
+
+
+def get_reference_store(request: Request) -> DirectoryStore[ReferenceId, Reference]:
+    return request.state.reference_store
+
+
+def get_content_store(request: Request) -> DirectoryStore[ContentId, Content]:
+    return request.state.content_store
+
+
+UserStoreDependency = Annotated[DirectoryStore[UserId, User], Depends(get_user_store)]
+WorkspaceStoreDependency = Annotated[
+    DirectoryStore[WorkspaceId, Workspace], Depends(get_workspace_store)
+]
+SnapshotDependency = Annotated[
+    DirectoryStore[SnapshotId, Snapshot], Depends(get_snapshot_store)
+]
+ManifestStoreDependency = Annotated[
+    DirectoryStore[ManifestId, Manifest], Depends(get_manifest_store)
+]
+ReferenceStoreDependency = Annotated[
+    DirectoryStore[ReferenceId, Reference], Depends(get_reference_store)
+]
+ContentStoreDependency = Annotated[
+    DirectoryStore[ContentId, Content], Depends(get_content_store)
+]
+
+
+@application.head(
+    "/user/{user_id}",
+)
+async def head_user(user_id: UserId, user_store: UserStoreDependency) -> None:
+    if not await user_store.contains(user_id):
+        raise HTTPException(404)
+
+
+@application.get(
+    "/user/{user_id}",
+)
+async def get_user(user_id: UserId, user_store: UserStoreDependency) -> Response:
+    if await user_store.contains(user_id):
+        return Response(dill.dumps(await user_store.get(user_id)))
+    raise HTTPException(404)
+
+
+@application.put(
+    "/user/{user_id}",
+)
+async def put_user(
+    user_id: UserId, request: Request, user_store: UserStoreDependency
+) -> None:
+    user: User = dill.loads(await request.body())  # noqa: S301
+    await user_store.set(user_id, user)
+
+
+@application.delete(
+    "/user/{user_id}",
+)
+async def delete_user(user_id: UserId, user_store: UserStoreDependency) -> None:
+    if user_store.contains(user_id):
+        await user_store.delete(user_id)
+
+
+@application.head(
+    "/workspace/{workspace_id}",
+)
+async def head_workspace(
+    workspace_id: WorkspaceId, workspace_store: WorkspaceStoreDependency
+) -> None:
+    if not await workspace_store.contains(workspace_id):
+        raise HTTPException(404)
+
+
+@application.get(
+    "/workspace/{workspace_id}",
+)
+async def get_workspace(
+    workspace_id: WorkspaceId, workspace_store: WorkspaceStoreDependency
+) -> Response:
+    if await workspace_store.contains(workspace_id):
+        return Response(dill.dumps(await workspace_store.get(workspace_id)))
+    raise HTTPException(404)
+
+
+@application.put(
+    "/workspace/{workspace_id}",
+)
+async def put_workspace(
+    workspace_id: WorkspaceId,
+    request: Request,
+    workspace_store: WorkspaceStoreDependency,
+) -> None:
+    workspace: Workspace = dill.loads(await request.body())  # noqa: S301
+    await workspace_store.set(workspace_id, workspace)
+
+
+@application.delete(
+    "/workspace/{workspace_id}",
+)
+async def delete_workspace(
+    workspace_id: WorkspaceId, workspace_store: WorkspaceStoreDependency
+) -> None:
+    if workspace_store.contains(workspace_id):
+        await workspace_store.delete(workspace_id)
+
+
+@application.head(
+    "/snapshot/{snapshot_id}",
+)
+async def head_snapshot(
+    snapshot_id: SnapshotId, snapshot_store: SnapshotDependency
+) -> None:
+    if not await snapshot_store.contains(snapshot_id):
+        raise HTTPException(404)
+
+
+@application.get(
+    "/snapshot/{snapshot_id}",
+)
+async def get_snapshot(
+    snapshot_id: SnapshotId, snapshot_store: SnapshotDependency
+) -> Response:
+    if await snapshot_store.contains(snapshot_id):
+        return Response(dill.dumps(await snapshot_store.get(snapshot_id)))
+    raise HTTPException(404)
+
+
+@application.put(
+    "/snapshot/{snapshot_id}",
+)
+async def put_snapshot(
+    snapshot_id: SnapshotId,
+    request: Request,
+    snapshot_store: SnapshotDependency,
+) -> None:
+    snapshot: Snapshot = dill.loads(await request.body())  # noqa: S301
+    await snapshot_store.set(snapshot_id, snapshot)
+
+
+@application.delete(
+    "/snapshot/{snapshot_id}",
+)
+async def delete_snapshot(
+    snapshot_id: SnapshotId, snapshot_store: SnapshotDependency
+) -> None:
+    if snapshot_store.contains(snapshot_id):
+        await snapshot_store.delete(snapshot_id)
+
+
+@application.head(
+    "/manifest/{manifest_id}",
+)
+async def head_manifest(
+    manifest_id: ManifestId, manifest_store: ManifestStoreDependency
+) -> None:
+    if not await manifest_store.contains(manifest_id):
+        raise HTTPException(404)
+
+
+@application.get(
+    "/manifest/{manifest_id}",
+)
+async def get_manifest(
+    manifest_id: ManifestId, manifest_store: ManifestStoreDependency
+) -> Response:
+    if await manifest_store.contains(manifest_id):
+        return Response(dill.dumps(await manifest_store.get(manifest_id)))
+    raise HTTPException(404)
+
+
+@application.put(
+    "/manifest/{manifest_id}",
+)
+async def put_manifest(
+    manifest_id: ManifestId,
+    request: Request,
+    manifest_store: ManifestStoreDependency,
+) -> None:
+    manifest: Manifest = dill.loads(await request.body())  # noqa: S301
+    await manifest_store.set(manifest_id, manifest)
+
+
+@application.delete(
+    "/manifest/{manifest_id}",
+)
+async def delete_manifest(
+    manifest_id: ManifestId, manifest_store: ManifestStoreDependency
+) -> None:
+    if manifest_store.contains(manifest_id):
+        await manifest_store.delete(manifest_id)
+
+
+@application.head(
+    "/reference/{reference_id}",
+)
+async def head_reference(
+    reference_id: ReferenceId, reference_store: ReferenceStoreDependency
+) -> None:
+    if not await reference_store.contains(reference_id):
+        raise HTTPException(404)
+
+
+@application.get(
+    "/reference/{reference_id}",
+)
+async def get_reference(
+    reference_id: ReferenceId, reference_store: ReferenceStoreDependency
+) -> Response:
+    if await reference_store.contains(reference_id):
+        return Response(dill.dumps(await reference_store.get(reference_id)))
+    raise HTTPException(404)
+
+
+@application.put(
+    "/reference/{reference_id}",
+)
+async def put_reference(
+    reference_id: ReferenceId,
+    request: Request,
+    reference_store: ReferenceStoreDependency,
+) -> None:
+    reference: Reference = dill.loads(await request.body())  # noqa: S301
+    await reference_store.set(reference_id, reference)
+
+
+@application.delete(
+    "/reference/{reference_id}",
+)
+async def delete_reference(
+    reference_id: ReferenceId, reference_store: ReferenceStoreDependency
+) -> None:
+    if reference_store.contains(reference_id):
+        await reference_store.delete(reference_id)
+
+
+@application.head(
+    "/content/{content_id}",
+)
+async def head_content(
+    content_id: ContentId, content_store: ContentStoreDependency
+) -> None:
+    if not await content_store.contains(content_id):
+        raise HTTPException(404)
+
+
+@application.get(
+    "/content/{content_id}",
+)
+async def get_content(
+    content_id: ContentId, content_store: ContentStoreDependency
+) -> Response:
+    if await content_store.contains(content_id):
+        return Response(dill.dumps(await content_store.get(content_id)))
+    raise HTTPException(404)
+
+
+@application.put(
+    "/content/{content_id}",
+)
+async def put_content(
+    content_id: ContentId,
+    request: Request,
+    content_store: ContentStoreDependency,
+) -> None:
+    content: Content = dill.loads(await request.body())  # noqa: S301
+    await content_store.set(content_id, content)
+
+
+@application.delete(
+    "/content/{content_id}",
+)
+async def delete_content(
+    content_id: ContentId, content_store: ContentStoreDependency
+) -> None:
+    if content_store.contains(content_id):
+        await content_store.delete(content_id)
+
+
+def main() -> None:
+    uvicorn.run("evserver:application")

evserver-0.3.0/src/evserver/stores.py

@@ -0,0 +1,33 @@
+from pathlib import Path  # noqa: TC003
+from typing import TYPE_CHECKING
+
+import dill
+
+if TYPE_CHECKING:
+    from evserver.types import Id
+
+
+class DirectoryStore[K, V]:
+    def __init__(self, root: Path) -> None:
+        root.mkdir(parents=True, exist_ok=True)
+        self.root = root
+
+    def _path(self, key: Id) -> Path:
+        return self.root / key
+
+    async def contains(self, key: Id) -> bool:
+        return self._path(key).exists()
+
+    async def set(self, key: Id, value: V) -> None:
+        path = self._path(key)
+        with path.open("wb") as f:
+            dill.dump(value, f)
+
+    async def get(self, key: Id) -> V:
+        path = self._path(key)
+        with path.open("rb") as f:
+            return dill.load(f)  # noqa: S301
+
+    async def delete(self, key: Id) -> None:
+        path = self._path(key)
+        path.unlink()

evserver-0.3.0/src/evserver/types.py

@@ -0,0 +1,70 @@
+from hashlib import sha3_512
+from pathlib import Path  # noqa: TC003
+
+from pydantic.dataclasses import dataclass
+
+type Id = str
+UserId = Id
+WorkspaceId = Id
+SnapshotId = Id
+ManifestId = Id
+ReferenceId = Id
+ContentId = Id
+
+
+@dataclass(slots=True)
+class User:
+    id: UserId
+
+
+@dataclass(slots=True)
+class Content:
+    data: bytes
+
+    @property
+    def id(self) -> ContentId:
+        return sha3_512(self.data).hexdigest()
+
+
+@dataclass(slots=True)
+class Reference:
+    file_path: Path
+    content_id: ContentId
+
+    @property
+    def id(self) -> ReferenceId:
+        return sha3_512(
+            str(self.file_path).encode() + self.content_id.encode()
+        ).hexdigest()
+
+
+@dataclass(slots=True)
+class Manifest:
+    reference_ids: set[ReferenceId]
+
+    @property
+    def id(self) -> ManifestId:
+        manifest_id = sha3_512()
+        for reference_id in self.reference_ids:
+            manifest_id.update(reference_id.encode())
+        return manifest_id.hexdigest()
+
+
+@dataclass(slots=True)
+class Snapshot:
+    manifest_id: ManifestId
+    note: str | None
+
+    @property
+    def id(self) -> SnapshotId:
+        snapshot_id = sha3_512()
+        snapshot_id.update(self.manifest_id.encode())
+        if self.note:
+            snapshot_id.update(self.note.encode())
+        return snapshot_id.hexdigest()
+
+
+@dataclass(slots=True)
+class Workspace:
+    snapshot_ids: set[SnapshotId]
+    id: WorkspaceId