LocalStorageProvider

LocalStorageProvider implements storage operations targeting the host filesystem. It defends against path traversal attacks by enforcing strict path bounds checks, generates high-entropy collision-free identifiers, resolves web-accessible URL paths dynamically, and evaluates uploaded files through configurable security validators.

Class Definition

from typing import Optional, List
from zcore.storage import LocalStorageProvider, StorageProvider, BaseStorageValidator

class LocalStorageProvider(StorageProvider):
    def __init__(
        self, 
        base_path: str = "./storage", 
        url_prefix: str = "/storage", 
        validators: Optional[List[BaseStorageValidator]] = None
    ) -> None:
        ...

Initialization Parameters

Methods

upload

Uploads an incoming file to the local directory. Runs configured validators, generates a collision-resistant UUID filename, and asynchronously streams chunks to disk.

async def upload(self, file: UploadFile, folder: str = "") -> str: ...

upload_stream

Directly streams binary raw chunks from an asynchronous generator to a local file destination.

async def upload_stream(
    self, 
    file_stream: AsyncGenerator[bytes, None], 
    filename: str, 
    folder: str = ""
) -> str: ...

delete

Securely removes a file from local storage using its physical path or web URL. Asserts that the target path resides within base_path before unlinking to prevent arbitrary file deletion exploits.

async def delete(self, file_path_or_url: str) -> bool: ...

exists

Verifies the physical presence of an asset within the local storage sandbox using its web URL or relative path.

async def exists(self, file_path_or_url: str) -> bool: ...

get_url

Resolves the normalized web-accessible URL for a stored asset.

async def get_url(self, file_path_or_url: str) -> str: ...