fix(server): restore put_document_file's workspace_name parameter

[JonnyTran]

Blocks a 0.7.2 release. v0.7.1 was cut, failed its integration suite, and was never published — this is the fix that makes it publishable.

The break

The obstore refactor (#244/#246) renamed put_document_file's second parameter to workspace but left both callers passing workspace_name=:

Caller	Path
api/handlers/v1/documents.py:82	POST /api/v1/documents
contexts/imports.py:432	bulk import

Every document upload raised TypeError: put_document_file() got an unexpected keyword argument 'workspace_name' and returned a 500. On v0.7.1:

FAILED tests/integration/test_workspace_documents.py::TestWorkspaceDocuments::test_add_document_with_file
  InternalServerError ... "message":"put_document_file() got an unexpected keyword argument 'workspace_name'"

Why the unit suite missed it

tests/unit/contexts/test_files_store.py:181 called it positionally, so the signature could drift from its callers without any unit test noticing. Integration caught it, but integration doesn't gate most PRs. That test now calls by keyword — the change that makes this class of break visible where it needs to be.

Which side to fix

I renamed the parameter rather than the two call sites. Worth stating the tradeoff, because the other direction is defensible:

• For renaming the parameter (this PR): put_document_file is exported and its v0.7.0 signature took workspace_name. Renaming it back keeps the public signature stable, so no out-of-repo caller has to change across the 0.7.x line.
• Against: contexts/files.py otherwise uses workspace universally — _put, put_object, get_object, delete_object, list_objects, delete_workspace_objects, delete_document_artifacts all do, and the module now contains exactly one workspace_name. By the module's own convention the callers were the outliers.

Happy to flip it to updating the two call sites if the reviewer prefers internal consistency over signature stability.

Verification

An AST scan of every keyword call against contexts/files.py signatures, run on both revisions, confirms the fix is complete and that this was the only such mismatch:

PRE-FIX (v0.7.1):
  contexts/imports.py:432                put_document_file(... workspace_name=...)
  api/handlers/v1/documents.py:82        put_document_file(... workspace_name=...)
POST-FIX:
  (no mismatches)

tests/unit: 1971 passed, 42 skipped. Three failures in tests/unit/security (test_jwt, test_default_security_settings) reproduce identically on unmodified main in the same environment and are unrelated — CI is green on main.

Summary by CodeRabbit

• Bug Fixes
  • Improved consistency when uploading document files to a workspace, ensuring existing files are checked and uploaded content is associated with the correct workspace.
  • Preserved existing duplicate-file handling and error behavior.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
extralit-frontend	Ignored	Preview	Aug 23, 2026 9:49pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: acf316f8-c7d0-4d6e-9b58-532f8b7e7221

📥 Commits

Reviewing files that changed from the base of the PR and between 45394f7 and dfc3328.

📒 Files selected for processing (2)

• extralit-server/src/extralit_server/contexts/files.py
• extralit-server/tests/unit/contexts/test_files_store.py

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The put_document_file parameter is renamed to workspace_name. Existing-file lookup, upload, and proxy URL generation use the renamed parameter. The related unit test now uses keyword arguments.

Changes

Document file workspace handling

Layer / File(s)	Summary
Update document upload workspace handling extralit-server/src/extralit_server/contexts/files.py, extralit-server/tests/unit/contexts/test_files_store.py	put_document_file uses workspace_name for file lookup, upload, and proxy URL generation. The upload test uses explicit keyword arguments.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Merge Risk: ⚪ Minimal · up to dfc33

This restores document uploads and bulk imports that were failing because callers used the public workspace_name parameter; no actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the fix and names the affected function and parameter.
Description check	✅ Passed	The description clearly explains the bug, impact, design choice, verification, and test results, although some template sections are omitted.
Docstring Coverage	✅ Passed	Docstring check was indeterminate for this PR — some files could not be analyzed in time. Not blocking.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/put-document-file-kwarg

Warning

Your free Security trial is over. An organization admin can activate billing to continue.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}