chore: import upstream snapshot with attribution

examples/python/seaweedfs/seaweedfs.py

@@ -0,0 +1,107 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import os
+
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.resource.seaweedfs import SeaweedFSConfig, SeaweedFSResource
+
+load_dotenv(".env.development")
+
+config = SeaweedFSConfig(
+    bucket=os.environ.get("SEAWEEDFS_BUCKET", "mirage-demo"),
+    endpoint_url=os.environ.get("SEAWEEDFS_ENDPOINT", "http://localhost:8333"),
+    access_key_id=os.environ.get("SEAWEEDFS_ACCESS_KEY", "any"),
+    secret_access_key=os.environ.get("SEAWEEDFS_SECRET_KEY", "any"),
+)
+resource = SeaweedFSResource(config)
+ws = Workspace({"/seaweedfs/": resource}, mode=MountMode.WRITE)
+
+
+def ops_summary() -> str:
+    records = ws.ops.records
+    total = sum(r.bytes for r in records)
+    return f"{len(records)} ops, {total} bytes transferred"
+
+
+async def main():
+    print(
+        f"=== SeaweedFS at {config.endpoint_url} (bucket {config.bucket}) ===")
+
+    # Seed a few objects so the demo is self-contained (WRITE mode).
+    await ws.ops.write(
+        "/seaweedfs/data/example.jsonl",
+        b'{"event":"queue-operation","tool":"mirage"}\n'
+        b'{"event":"read","tool":"mirage"}\n'
+        b'{"event":"queue-operation","tool":"other"}\n')
+    await ws.ops.write(
+        "/seaweedfs/data/config.json",
+        b'{"name":"mirage","version":1,"tags":["s3","seaweedfs"]}')
+    await ws.ops.write("/seaweedfs/notes.txt", b"hello from seaweedfs\n")
+
+    print("\n--- ls /seaweedfs/ ---")
+    r = await ws.execute("ls /seaweedfs/")
+    print(await r.stdout_str())
+
+    print("--- tree /seaweedfs/ ---")
+    r = await ws.execute("tree /seaweedfs/")
+    print(await r.stdout_str())
+
+    print("--- stat /seaweedfs/notes.txt ---")
+    r = await ws.execute("stat /seaweedfs/notes.txt")
+    print(f"  {(await r.stdout_str()).strip()}")
+
+    print("\n--- cat /seaweedfs/notes.txt ---")
+    r = await ws.execute("cat /seaweedfs/notes.txt")
+    print(f"  {(await r.stdout_str()).strip()!r}")
+
+    print("\n--- head -c 40 /seaweedfs/data/example.jsonl (byte range) ---")
+    r = await ws.execute("head -c 40 /seaweedfs/data/example.jsonl")
+    print(f"  {(await r.stdout_str()).strip()!r}")
+
+    print("\n--- grep -c queue-operation /seaweedfs/data/example.jsonl ---")
+    r = await ws.execute(
+        "grep -c queue-operation /seaweedfs/data/example.jsonl")
+    print(f"  count: {(await r.stdout_str()).strip()}")
+
+    print("--- find /seaweedfs/ -name '*.json' ---")
+    r = await ws.execute("find /seaweedfs/ -name '*.json'")
+    print(await r.stdout_str())
+
+    print("--- jq .tags /seaweedfs/data/config.json ---")
+    r = await ws.execute("jq .tags /seaweedfs/data/config.json")
+    print(f"  {(await r.stdout_str()).strip()}")
+
+    print("\n--- PROVISION: cat (plan only) vs head -c (byte budget) ---")
+    dr = await ws.execute("cat /seaweedfs/data/example.jsonl", provision=True)
+    print(f"  cat: network_read={dr.network_read} precision={dr.precision}")
+    dr = await ws.execute("head -c 20 /seaweedfs/data/example.jsonl",
+                          provision=True)
+    print(f"  head -c 20: network_read={dr.network_read} "
+          f"precision={dr.precision}")
+
+    print("\n--- rm seeded objects ---")
+    for key in ("/seaweedfs/data/example.jsonl", "/seaweedfs/data/config.json",
+                "/seaweedfs/notes.txt"):
+        await ws.execute(f"rm {key}")
+    print("  cleaned")
+
+    print(f"\nStats: {ops_summary()}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/seaweedfs/seaweedfs_fuse.py

@@ -0,0 +1,91 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import os
+
+from dotenv import load_dotenv
+
+from mirage import Mount, MountMode, Workspace
+from mirage.resource.seaweedfs import SeaweedFSConfig, SeaweedFSResource
+
+load_dotenv(".env.development")
+
+config = SeaweedFSConfig(
+    bucket=os.environ.get("SEAWEEDFS_BUCKET", "mirage-demo"),
+    endpoint_url=os.environ.get("SEAWEEDFS_ENDPOINT", "http://localhost:8333"),
+    access_key_id=os.environ.get("SEAWEEDFS_ACCESS_KEY", "any"),
+    secret_access_key=os.environ.get("SEAWEEDFS_SECRET_KEY", "any"),
+)
+
+resource = SeaweedFSResource(config)
+
+SEED_KEYS = ("/seaweedfs/data/example.jsonl", "/seaweedfs/data/config.json",
+             "/seaweedfs/notes.txt")
+
+
+async def seed(ws: Workspace) -> None:
+    await ws.ops.write(
+        "/seaweedfs/data/example.jsonl",
+        b'{"event":"queue-operation","tool":"mirage"}\n'
+        b'{"event":"read","tool":"mirage"}\n'
+        b'{"event":"queue-operation","tool":"other"}\n')
+    await ws.ops.write(
+        "/seaweedfs/data/config.json",
+        b'{"name":"mirage","version":1,"tags":["s3","seaweedfs"]}')
+    await ws.ops.write("/seaweedfs/notes.txt", b"hello from seaweedfs\n")
+
+
+async def cleanup(ws: Workspace) -> None:
+    for key in SEED_KEYS:
+        await ws.execute(f"rm {key}")
+
+
+mounts = {"/seaweedfs/": Mount(resource, mode=MountMode.WRITE, fuse=True)}
+with Workspace(mounts) as ws:
+    asyncio.run(seed(ws))
+    mp = ws.fuse_mountpoint
+
+    print(f"=== FUSE MODE: SeaweedFS mounted at {mp} ===\n")
+
+    print("--- os.listdir() ---")
+    for e in os.listdir(f"{mp}/data"):
+        print(f"  {e}")
+
+    print("\n--- open() + read ---")
+    with open(f"{mp}/data/example.jsonl") as f:
+        for i, line in enumerate(f):
+            if i >= 3:
+                break
+            print(f"  [{i}] {line.strip()[:100]}...")
+
+    print("\n--- os.path.getsize() ---")
+    size = os.path.getsize(f"{mp}/data/example.jsonl")
+    print(f"  size: {size} bytes")
+
+    print(f"\n>>> FUSE mounted at: {mp}")
+    print(">>> Open another terminal and run:")
+    print(f">>>   ls {mp}/data/")
+    print(f">>>   cat {mp}/data/config.json")
+    print(">>> Press Enter to unmount and exit...")
+    try:
+        input()
+    except EOFError:
+        pass
+
+    asyncio.run(cleanup(ws))
+
+    records = ws.ops.records
+    total = sum(r.bytes for r in records)
+    print(f"\nStats: {len(records)} ops, {total} bytes transferred")

examples/python/seaweedfs/seaweedfs_vfs.py

@@ -0,0 +1,99 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import json
+import os
+import sys
+
+from dotenv import load_dotenv
+
+from mirage import MountMode, Workspace
+from mirage.resource.seaweedfs import SeaweedFSConfig, SeaweedFSResource
+
+load_dotenv(".env.development")
+
+config = SeaweedFSConfig(
+    bucket=os.environ.get("SEAWEEDFS_BUCKET", "mirage-demo"),
+    endpoint_url=os.environ.get("SEAWEEDFS_ENDPOINT", "http://localhost:8333"),
+    access_key_id=os.environ.get("SEAWEEDFS_ACCESS_KEY", "any"),
+    secret_access_key=os.environ.get("SEAWEEDFS_SECRET_KEY", "any"),
+)
+
+resource = SeaweedFSResource(config)
+
+
+async def main():
+    with Workspace({"/seaweedfs/": resource}, mode=MountMode.WRITE) as ws:
+        vos = sys.modules["os"]
+        print(f"=== VFS MODE: open() reads SeaweedFS at {config.endpoint_url} "
+              f"transparently ===\n")
+
+        # Seed a few objects so the demo is self-contained.
+        await ws.ops.write(
+            "/seaweedfs/data/example.jsonl",
+            b'{"event":"queue-operation","tool":"mirage"}\n'
+            b'{"event":"read","tool":"mirage"}\n'
+            b'{"event":"queue-operation","tool":"other"}\n')
+        await ws.ops.write(
+            "/seaweedfs/data/config.json",
+            b'{"name":"mirage","version":1,"tags":["s3","seaweedfs"]}')
+        await ws.ops.write("/seaweedfs/notes.txt", b"hello from seaweedfs\n")
+
+        print("--- os.listdir() root ---")
+        for e in vos.listdir("/seaweedfs"):
+            print(f"  {e}")
+
+        print("\n--- os.path.isdir() on prefix ---")
+        print(f"  /seaweedfs/data: {vos.path.isdir('/seaweedfs/data')}")
+
+        print("\n--- os.listdir() data ---")
+        for e in vos.listdir("/seaweedfs/data"):
+            print(f"  {e}")
+
+        print("\n--- open() + read example.jsonl (first 3 lines) ---")
+        with open("/seaweedfs/data/example.jsonl") as f:
+            for i, line in enumerate(f):
+                if i >= 3:
+                    break
+                rec = json.loads(line)
+                print(f"  [{i}] {json.dumps(rec)[:100]}...")
+
+        print("\n--- os.path.exists() ---")
+        print(f"  example.jsonl: "
+              f"{vos.path.exists('/seaweedfs/data/example.jsonl')}")
+        print(f"  nonexistent: {vos.path.exists('/seaweedfs/data/nope.txt')}")
+
+        print("\n--- os.path.getsize() ---")
+        print(f"  notes.txt: {vos.path.getsize('/seaweedfs/notes.txt')} bytes")
+
+        print("\n--- VFS commands ---")
+        result = await ws.execute("grep -c queue-operation "
+                                  "/seaweedfs/data/example.jsonl")
+        print(f"  grep matches: {(await result.stdout_str()).strip()}")
+        result = await ws.execute("jq .tags /seaweedfs/data/config.json")
+        print(f"  jq .tags    : {(await result.stdout_str()).strip()}")
+
+        print("\n--- cleanup ---")
+        for key in ("/seaweedfs/data/example.jsonl",
+                    "/seaweedfs/data/config.json", "/seaweedfs/notes.txt"):
+            await ws.execute(f"rm {key}")
+        print("  cleaned")
+
+        records = ws.ops.records
+        total = sum(r.bytes for r in records)
+        print(f"\nStats: {len(records)} ops, {total} bytes transferred")
+
+
+asyncio.run(main())