aquilia-cache-storage-filesystem - SKILL.md Agent Skill

name: aquilia-cache-storage-filesystem description: "Build Aquilia cache, storage, and native filesystem workflows. Use for CacheService/backends/decorators, StorageConfig/backends/registry/effects, local/S3/GCS/Azure/SFTP/memory storage, and aquilia.filesystem async file operations/security."

Aquilia Cache Storage Filesystem

Purpose

Use Aquilia's implemented cache, storage, and filesystem layers for data, blobs, and async file operations.

Trigger Conditions

Use for cache configuration, @cached, invalidation, memory/redis/composite cache, storage backends, file uploads/downloads, path traversal protection, async open/read/write/copy/move/delete, or storage effects.

Inputs

Cache backend, TTL, namespace, key builder, serializer, and secret key if needed.
Storage backend config: local, memory, S3, GCS, Azure Blob, SFTP, or composite.
File paths, roots, streaming requirements, and security constraints.

Execution Flow

Configure cache through Integration.cache(...) or cache-specific config; use CacheService and decorators for app code.
Configure storage through Workspace.storage(...) or Integration.storage(...); create backends via storage registry.
Use aquilia.filesystem async helpers for local filesystem work with validation.
For user-controlled paths, validate/sanitize with filesystem and storage security helpers.
Test with memory/local backends before cloud backends.

Constraints

Do not bypass path validation for user-controlled names.
Redis cache/socket backends require optional redis dependencies.
Cloud storage providers require credentials and optional SDKs; keep credentials out of generated code.

Implementation Anchors

aquilia/cache/, aquilia/storage/, aquilia/filesystem/, aquilia/storage/backends/, aquilia/cache/backends/, tests/test_storage_system.py, tests/test_filesystem_comprehensive.py, examples/cache_http_edge_app/, examples/storage_filehub_app/.

Examples

Add Integration.cache(backend="memory", default_ttl=300).
Configure local storage with root var/uploads.
Use await write_file(path, data) after validating relative paths.

Failure Handling

Cache serialization failures map to cache faults. Storage missing files use storage faults, not builtin exceptions. Path traversal and null byte attempts should be rejected before I/O.