feat: make file uploads directory configurable via config.toml

[Br1an67]

What

Add a files_dir option to [features.spontaneous_file_upload] in config.toml to override the default .files directory.

Closes #2155

Why

The .files directory is hardcoded, which is problematic when Chainlit runs in environments where the user doesn't control the app directory.

Changes

• backend/chainlit/config.py: Add files_dir: str = ".files" to SpontaneousFileUploadFeature, add it to TOML template, replace module-level FILES_DIRECTORY with get_files_directory() function that resolves relative paths from APP_ROOT
• backend/chainlit/session.py: Use get_files_directory() instead of FILES_DIRECTORY
• backend/chainlit/server.py: Use get_files_directory() for cleanup on shutdown
• backend/tests/test_session.py: Update patches to mock get_files_directory

Usage

[features.spontaneous_file_upload]
files_dir = "/var/data/chainlit-uploads"

Relative paths (e.g. files_dir = "uploads") resolve from the app root.

Testing

All 35 session tests pass. Default behavior unchanged (.files directory).

---

Summary by cubic

Make the uploads directory configurable via config.toml and harden file handling. Defaults to .files; relative paths resolve from the app root.

• New Features

  • Add files_dir to [features.spontaneous_file_upload] to override the uploads directory.
  • Resolve relative paths from CHAINLIT_APP_ROOT; absolute paths work as-is.
  • Use get_files_directory for session storage and server cleanup.

• Bug Fixes

  • Guard against missing spontaneous_file_upload config.
  • Create upload dirs on demand with mkdir(parents=True) instead of at import.
  • Only delete uploads under APP_ROOT on shutdown (including the default .files).

^{Written for commit 475ac36. Summary will update on new commits.}

[cubic-dev-ai]

3 issues found across 4 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="backend/chainlit/server.py">

<violation number="1" location="backend/chainlit/server.py:189">
P2: Shutdown cleanup now recursively deletes the user-configured files_dir without restricting it to an app-owned path, so setting files_dir to a shared or persistent directory can wipe arbitrary data on shutdown.</violation>
</file>

<file name="backend/chainlit/config.py">

<violation number="1" location="backend/chainlit/config.py:691">
P2: Upload directory is no longer created; get_files_directory returns a path without ensuring it exists, and callers mkdir only the session subdir without parents. On fresh installs/custom paths this can raise FileNotFoundError and break uploads.</violation>

<violation number="2" location="backend/chainlit/config.py:693">
P2: get_files_directory dereferences config.features.spontaneous_file_upload without guarding against it being None, which can raise AttributeError when the config omits the [features.spontaneous_file_upload] section.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[Br1an67]

Hi — just a gentle bump on this. Happy to make any changes if needed!

[hayescode]

Reviewed via Codex

LGTM.

[hayescode]

@Br1an67 please fix the failing CI then we should be good to merge!