mfup-fastapi 0.2.0__tar.gz

mfup_fastapi-0.2.0/.gitignore

@@ -0,0 +1,14 @@
+node_modules/
+dist/
+*.egg-info/
+__pycache__/
+.vite/
+uploads/
+repomix-output.md
+*.url
+repomix.sh
+# e2e artifacts
+e2e/.tmp/
+e2e/test-results/
+e2e/playwright-report/
+e2e/webtop/testdata/

mfup_fastapi-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 n0isy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mfup_fastapi-0.2.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: mfup-fastapi
+Version: 0.2.0
+Summary: FastAPI integration for the MFUP/2 upload engine: MfupEngine + APIRouter you mount into your own app, or a ready-to-run standalone server.
+Project-URL: Homepage, https://github.com/n0isy/mfup
+Project-URL: Repository, https://github.com/n0isy/mfup
+Project-URL: Issues, https://github.com/n0isy/mfup/issues
+Author: n0isy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fastapi,mfup,multi-file,resumable,upload
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: mfup-core==0.2.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Requires-Dist: websockets>=13.0
+Provides-Extra: dev
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mfup-fastapi
+
+FastAPI integration for the MFUP/2 resumable multi-file upload engine
+([`mfup-core`](https://pypi.org/project/mfup-core/)).
+
+## Embed into your app
+
+```python
+from pathlib import Path
+from fastapi import FastAPI
+from mfup_fastapi import MfupConfig, MfupEngine
+from mfup_core import AuthRequest, AuthResult
+
+async def authorize(req: AuthRequest) -> AuthResult | None:
+    user = await my_auth(req.headers)          # cookies / Authorization
+    if user is None:
+        return None                            # → SESSION_ABORT(auth_failed)
+    return AuthResult(
+        base_dir=f"/srv/homes/{user.id}",      # per-user home
+        max_total_bytes=10 * 2**30,            # 10 GiB quota
+        context={"user_id": user.id},
+    )
+
+engine = MfupEngine(MfupConfig(
+    base_dir=Path("/srv/uploads"),
+    redis_url="redis://localhost:6379/0",
+    authorize=authorize,                       # a callable — or "pkg.mod:func"
+))
+
+app = FastAPI(lifespan=engine.lifespan)
+app.include_router(engine.router, prefix="/api/uploads")
+```
+
+Point the browser SDK (`@mfup/client` on npm) at the same prefix:
+`new MfupSession({ serverUrl: "https://host/api/uploads" })`.
+
+## Run standalone
+
+```bash
+pip install mfup-fastapi
+MFUP_BASE_DIR=/srv/uploads REDIS_URL=redis://localhost:6379/0 \
+  python -m mfup_fastapi
+```
+
+All `MfupConfig` fields map 1:1 to `MFUP_*` environment variables
+(`MfupConfig.from_env()`); hooks are dotted paths there
+(`MFUP_AUTHORIZE=myapp.uploads:authorize`).
+
+## Hooks
+
+| Hook | When | Controls |
+|---|---|---|
+| `authorize` | HELLO, before anything is created | allow/deny, per-user `base_dir`, target mapping, byte/file quotas, `context` |
+| `map_file` | publish, per file | final layout (by type/scope/anything) |
+| `on_committed` | after COMMIT_OK | notification; return `"publish"` to publish server-side (scan/moderation/billing flows). Or call `engine.publish(session_id)` yourself later. |
+
+Requires Redis (expiry index) and a POSIX filesystem. One worker per engine
+instance; resume across workers is handled via lazy recovery from the Redis
+index. Full contract: `docs/EXTENDING.md` in the repository.
+
+Docs and source: <https://github.com/n0isy/mfup>

mfup_fastapi-0.2.0/README.md

@@ -0,0 +1,61 @@
+# mfup-fastapi
+
+FastAPI integration for the MFUP/2 resumable multi-file upload engine
+([`mfup-core`](https://pypi.org/project/mfup-core/)).
+
+## Embed into your app
+
+```python
+from pathlib import Path
+from fastapi import FastAPI
+from mfup_fastapi import MfupConfig, MfupEngine
+from mfup_core import AuthRequest, AuthResult
+
+async def authorize(req: AuthRequest) -> AuthResult | None:
+    user = await my_auth(req.headers)          # cookies / Authorization
+    if user is None:
+        return None                            # → SESSION_ABORT(auth_failed)
+    return AuthResult(
+        base_dir=f"/srv/homes/{user.id}",      # per-user home
+        max_total_bytes=10 * 2**30,            # 10 GiB quota
+        context={"user_id": user.id},
+    )
+
+engine = MfupEngine(MfupConfig(
+    base_dir=Path("/srv/uploads"),
+    redis_url="redis://localhost:6379/0",
+    authorize=authorize,                       # a callable — or "pkg.mod:func"
+))
+
+app = FastAPI(lifespan=engine.lifespan)
+app.include_router(engine.router, prefix="/api/uploads")
+```
+
+Point the browser SDK (`@mfup/client` on npm) at the same prefix:
+`new MfupSession({ serverUrl: "https://host/api/uploads" })`.
+
+## Run standalone
+
+```bash
+pip install mfup-fastapi
+MFUP_BASE_DIR=/srv/uploads REDIS_URL=redis://localhost:6379/0 \
+  python -m mfup_fastapi
+```
+
+All `MfupConfig` fields map 1:1 to `MFUP_*` environment variables
+(`MfupConfig.from_env()`); hooks are dotted paths there
+(`MFUP_AUTHORIZE=myapp.uploads:authorize`).
+
+## Hooks
+
+| Hook | When | Controls |
+|---|---|---|
+| `authorize` | HELLO, before anything is created | allow/deny, per-user `base_dir`, target mapping, byte/file quotas, `context` |
+| `map_file` | publish, per file | final layout (by type/scope/anything) |
+| `on_committed` | after COMMIT_OK | notification; return `"publish"` to publish server-side (scan/moderation/billing flows). Or call `engine.publish(session_id)` yourself later. |
+
+Requires Redis (expiry index) and a POSIX filesystem. One worker per engine
+instance; resume across workers is handled via lazy recovery from the Redis
+index. Full contract: `docs/EXTENDING.md` in the repository.
+
+Docs and source: <https://github.com/n0isy/mfup>

mfup_fastapi-0.2.0/mfup_fastapi/__init__.py

@@ -0,0 +1,40 @@
+"""mfup-fastapi — FastAPI integration for the MFUP/2 upload engine.
+
+    from mfup_fastapi import MfupConfig, MfupEngine, create_app
+"""
+
+from .config import MfupConfig
+from .engine import (
+    MapFileHookError,
+    MfupEngine,
+    NotCommitted,
+    PublishError,
+    SessionNotFound,
+    TargetEscapes,
+    reconcile_orphans,
+)
+
+
+def create_app(config: "MfupConfig | None" = None):
+    """Lazy re-export: builds the standalone app without importing
+    mfup_fastapi.app (which reads the environment at import time)."""
+    from fastapi import FastAPI
+
+    engine = MfupEngine(config or MfupConfig.from_env())
+    app = FastAPI(title="MFUP/2 Server", lifespan=engine.lifespan)
+    app.include_router(engine.router)
+    app.state.mfup_engine = engine
+    return app
+
+
+__all__ = [
+    "create_app",
+    "MapFileHookError",
+    "MfupConfig",
+    "MfupEngine",
+    "NotCommitted",
+    "PublishError",
+    "reconcile_orphans",
+    "SessionNotFound",
+    "TargetEscapes",
+]

mfup_fastapi-0.2.0/mfup_fastapi/__main__.py

@@ -0,0 +1,13 @@
+"""Run the standalone MFUP/2 server: python -m mfup_fastapi"""
+
+import os
+
+import uvicorn
+
+if __name__ == "__main__":
+    uvicorn.run(
+        "mfup_fastapi.app:app",
+        host=os.environ.get("MFUP_HOST", "0.0.0.0"),
+        port=int(os.environ.get("MFUP_PORT", "8070")),
+        log_level="info",
+    )

mfup_fastapi-0.2.0/mfup_fastapi/app.py

@@ -0,0 +1,18 @@
+"""Standalone MFUP/2 server — config from environment.
+
+    uvicorn mfup_fastapi.app:app
+
+This module is the ONLY place that builds an app at import time
+(``app = create_app()`` for uvicorn's module:attr convention). Library
+consumers use MfupEngine/MfupConfig directly and never import this module.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from . import create_app
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(name)s %(levelname)s %(message)s")
+
+app = create_app()

mfup_fastapi-0.2.0/mfup_fastapi/config.py

@@ -0,0 +1,78 @@
+"""MfupConfig — every knob of the FastAPI integration in one dataclass.
+
+Two construction paths:
+  - ``MfupConfig(...)``          — library embedding, explicit values,
+                                   hooks as CALLABLES;
+  - ``MfupConfig.from_env()``    — standalone/container deployment, values
+                                   from MFUP_* env vars, hooks as dotted
+                                   paths ("pkg.module:callable").
+
+No environment variable is read at import time anywhere in this package —
+only from_env() touches os.environ.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Mapping, Optional, Union
+
+#: A hook is either the callable itself or a dotted import path.
+HookRef = Union[str, Callable[..., Any]]
+
+
+@dataclass
+class MfupConfig:
+    #: Global base directory for staging + publish (per-session base_dir from
+    #: the authorize hook overrides it per session).
+    base_dir: Path = Path("/tmp/mfup-uploads")
+    redis_url: str = "redis://redis:6379/0"
+    session_resume_ttl: int = 3600
+    leg_idle_timeout: int = 60
+    max_chunk_bytes: int = 262144
+    max_open_files: int = 1
+    max_pending_files: int = 64
+    sweep_interval: int = 300
+    staging_prefix: str = ".incoming"
+    #: Run the filesystem-orphan reconciliation every Nth sweep.
+    reconcile_every: int = 4
+    #: Minimum age before a staging dir may be reconciled as an orphan.
+    orphan_grace_seconds: int = 600
+    #: Buffered-body threshold for atomic batch POSTs.
+    max_buffered_body: int = 16 * 1024 * 1024
+    #: Cap on the JSON size of HELLO.meta.
+    max_meta_bytes: int = 16384
+    #: Bearer token for admin/debug routes. Empty → routes disabled.
+    admin_token: str = ""
+    #: Consumer hooks — callables or dotted paths (see mfup_core.hooks).
+    authorize: Optional[HookRef] = None
+    map_file: Optional[HookRef] = None
+    on_committed: Optional[HookRef] = None
+
+    @classmethod
+    def from_env(cls, env: Optional[Mapping[str, str]] = None) -> "MfupConfig":
+        e: Mapping[str, str] = os.environ if env is None else env
+
+        def _int(name: str, default: int) -> int:
+            return int(e.get(name, str(default)))
+
+        return cls(
+            base_dir=Path(e.get("MFUP_BASE_DIR", "/tmp/mfup-uploads")),
+            redis_url=e.get("REDIS_URL", "redis://redis:6379/0"),
+            session_resume_ttl=_int("MFUP_SESSION_RESUME_TTL", 3600),
+            leg_idle_timeout=_int("MFUP_LEG_IDLE_TIMEOUT", 60),
+            max_chunk_bytes=_int("MFUP_MAX_CHUNK_BYTES", 262144),
+            max_open_files=_int("MFUP_MAX_OPEN_FILES", 1),
+            max_pending_files=_int("MFUP_MAX_PENDING_FILES", 64),
+            sweep_interval=_int("MFUP_SWEEP_INTERVAL", 300),
+            staging_prefix=e.get("MFUP_STAGING_PREFIX", ".incoming"),
+            reconcile_every=_int("MFUP_RECONCILE_EVERY", 4),
+            orphan_grace_seconds=_int("MFUP_ORPHAN_GRACE", 600),
+            max_buffered_body=_int("MFUP_MAX_BUFFERED_BODY", 16 * 1024 * 1024),
+            max_meta_bytes=_int("MFUP_MAX_META_BYTES", 16384),
+            admin_token=e.get("MFUP_ADMIN_TOKEN", ""),
+            authorize=e.get("MFUP_AUTHORIZE") or None,
+            map_file=e.get("MFUP_MAP_FILE") or None,
+            on_committed=e.get("MFUP_ON_COMMITTED") or None,
+        )