# Phase 3: Server Integration (REST)

## Objective
Attach drive operations to `backend/src/server/web.py` using standard web routes only. This supersedes the WebSocket-based protocol from `drives-report.md`: no WS actions (`list-drives`, `list-files`, `upload-file`), no chunked transfer. Upstream transfer is a single `multipart/form-data` POST per file.

Assumes `drive_service` from the earlier phases provides `init_drives`, `upload_file`, `get_drive_file_metadata` and `resolve_drive_file_for_serving`.

## Routes

| Route | Method | Description |
|-------|--------|-------------|
| `/drives` | GET | List drives of the authenticated user. |
| `/drives/<drive_name>/files` | GET | List file metadata for one drive. |
| `/drives/<drive_name>/files` | POST | Upload one file (multipart, field `file`). Creates the drive if missing. |
| `/files/<int:file_id>` | GET | Raw download. |
| `/files/<int:file_id>/meta` | GET | Metadata for existence checks. |

### Auth
Reuse the existing `QuartAuth(server, mode="bearer")` setup:
- JSON endpoints use `@login_required` and read the user id from `current_user.auth_id`.
- `GET /files/<id>` additionally accepts `?token=`, because `<a download>` links cannot set an `Authorization` header.

## Implementation

### 3.1 Imports

Top of `backend/src/server/web.py`:

```python
import database as db
import drive_service
from quart import Quart, request, send_from_directory, send_file
from quart_auth import QuartAuth, AuthUser, login_user, login_required, current_user
```

### 3.2 Route handlers

Registered inside `start_server`, alongside the existing routes:

```python
@server.route('/drives', methods=['GET'])
@login_required
async def list_drives():
    drives = await db.Drive.filter(user_id=current_user.auth_id)
    return [{"id": d.id, "name": d.name} for d in drives]

@server.route('/drives/<drive_name>/files', methods=['GET'])
@login_required
async def list_files(drive_name):
    files = await db.DriveFile.filter(drive__user_id=current_user.auth_id, drive__name=drive_name)
    return [{
        "id": f.id,
        "name": f.filename,
        "size": f.size_bytes,
        "mime": f.mime_type,
        "created": f.created_at.isoformat(),
    } for f in files]

@server.route('/drives/<drive_name>/files', methods=['POST'])
@login_required
async def upload_file(drive_name):
# whole file in one request, no partial transmission
    upload = (await request.files).get('file')
    if upload is None:
        return "missing file part", 400
    file_id = await drive_service.upload_file(
        current_user.auth_id, drive_name, upload.filename, upload.stream, upload.content_type,
    )
    return {"fileId": file_id}

@server.route('/files/<int:file_id>', methods=['GET'])
async def serve_file(file_id):
# query token instead of @login_required: anchor downloads can't set headers
    user_id = auth_manager.load_token(request.args.get('token', ''))
    if user_id is None:
        return "unauthorized", 401
    try:
        file_path, mime_type = await drive_service.resolve_drive_file_for_serving(file_id, user_id)
        return await send_file(file_path, mimetype=mime_type)
    except FileNotFoundError:
        return "not found", 404
    except PermissionError:
        return "forbidden", 403

@server.route('/files/<int:file_id>/meta', methods=['GET'])
@login_required
async def get_file_meta(file_id):
    try:
# resolve performs the ownership check before anything is returned
        await drive_service.resolve_drive_file_for_serving(file_id, current_user.auth_id)
        return await drive_service.get_drive_file_metadata(file_id)
    except FileNotFoundError:
        return "not found", 404
    except PermissionError:
        return "forbidden", 403
```

No changes to `server/websocket.py`.

## Frontend protocol

```javascript
// listing
const drives = await fetch('/drives', {headers: {Authorization: `Bearer ${token}`}}).then(r => r.json());
const files = await fetch(`/drives/${encodeURIComponent(name)}/files`, {headers: {Authorization: `Bearer ${token}`}}).then(r => r.json());

// upload: single POST, no chunking
const form = new FormData();
form.append('file', blob, 'report.pdf');
await fetch(`/drives/${encodeURIComponent(driveName)}/files`, {
    method: 'POST',
    headers: {Authorization: `Bearer ${token}`},
    body: form,
});

// download: plain anchor
// <a href={`/files/${fileId}?token=${token}`} download={file.name}>Download</a>
```

## Notes

- Routing is unaffected by the static catch-all: werkzeug prefers the exact/typed routes above over `/<path:path>`.
- `/drives` is now an API route; the SPA must not mount a view at that exact path.
- `drive_name` is a single URL segment (no `/`). The service layer should reject names containing path separators before they reach `os.path.join`.
- The query-token on the download endpoint trades header auth for `<a download>` compatibility (token visible in history/logs). Switch to fetch + blob or cookie auth if that's unacceptable.