darca-storage 0.0.1

Storage instance with file operation support for multiple backends.

Async-first, secure, and extensible storage backend abstraction for the Darca ecosystem.

darca-storage provides a clean interface for reading and writing to structured storage backends — local, cloud, or custom — with support for path confinement, credential injection, and session-aware logic.

---

---

Features

• ✅ Async-compatible FileBackend interface

• 🔐 Scoped access via ScopedFileBackend

• 🧠 Session-aware StorageClient with observability

• 🔌 Pluggable storage connectors (e.g., file://)

• 🔄 Credential and user context propagation

• 🧪 Easy to test and extend

---

📦 Installation

pip install darca-storage

Or using Poetry:

poetry add darca-storage

---

Quick Example

from darca_storage.factory import StorageConnectorFactory

client = await StorageConnectorFactory.from_url("file:///tmp/darca")

await client.write("hello.txt", content="Hello Darca!")
text = await client.read("hello.txt")
print(text)

---

Security by Default

All paths are resolved via ScopedFileBackend, which:

• Normalizes and confines all access to a declared base_path

• Prevents path traversal (e.g., ../../etc/passwd)

• Raises StorageClientPathViolation if the boundary is violated

---

Extending

Implement a new backend:

class MyBackend(FileBackend):
    async def read(self, path: str, *, binary=False) -> Union[str, bytes]:
        ...

Implement a new connector:

class MyConnector(StorageConnector):
    async def connect(self) -> FileBackend:
        return ScopedFileBackend(...)

Then register your scheme inside StorageConnectorFactory.

---

📚 Documentation

Visit the full documentation:

👉 https://roelkist.github.io/darca-storage/

To build locally:

make docs

---

🧪 Testing

Run all tests using:

make test

Coverage and reports:

• Generates coverage.svg badge

• Stores HTML output in htmlcov/

• Fully parallel test support with xdist

---

🤝 Contributing

We welcome all contributions!

• Create a new branch from main

• Use PRs to submit changes

• You can also open feature requests or issues using our GitHub templates

See CONTRIBUTING.rst for detailed guidelines.

---

📄 License

This project is licensed under the MIT License. See LICENSE for details.