✨ POC: integrate Docs documents in the Drive tree - #790
Draft
NathanVss wants to merge 6 commits into
Draft
Conversation
Resources hosted by other applications (e.g. Docs documents) need to live in the Drive tree next to regular files. A metadata.external_app marker turns a FILE item into a pointer: it carries no filename and no physical upload, is ready as soon as created, and can hold children so an app can model sub-resources. Abilities gate every file-only feature (download, wopi, upload, convert) and soft delete now propagates to descendants of such items like it does for folders.
External apps integrated in the tree must enforce the exact same permissions as Drive without duplicating them. A static bearer token identifies the trusted app and the X-User-Sub/X-User-Email headers name the acting user, so every existing endpoint keeps its permission logic. Without identity headers the caller acts for an anonymous visitor, which makes public-link reach work end to end. The returned "s2s" auth tag lets views detect these calls to prevent notification loops.
Integrating a new application must not require touching the item views. Each app configured in EXTERNAL_APPS provides a backend implementing a small contract (create, delete, restore, purge resources) resolved by name from the item metadata. The Docs backend is the first implementation, calling the Docs server-to-server endpoints. The FRONTEND_DOCS_URL setting is kept as a real setting because the config endpoint exposes it to the frontend.
The external app must mirror what happens to its pointer items in Drive. Creating one from Drive triggers the app back-channel (rolled back if the app fails), and trash, restore and purge notify the app for every pointer of the affected subtree. The purge task carries a backstop notification so the cron path is covered too; app endpoints are idempotent so retries are safe. Server-to-server calls skip all hooks because the app initiated the operation itself. Sub-documents (children of a pointer item) are hidden from all listing views so only the document root surfaces in the UI, while the new tree-descendants action returns the whole document tree to the app.
Docs documents live in the tree as pointer items, so the explorer needs to treat them specially: a dedicated create menu entry posts an item carrying the docs metadata (same UX as template files, no auto-open), the grid shows the Docs icon, and clicking one opens the Docs frontend instead of the preview. The file preview route hands over to Docs too, so shared links to the item keep working.
Running the POC locally needs the two apps to trust each other: a dev placeholder token shared by both directions of the server-to-server API, the Docs URLs resolvable from the compose network, and an impress client in the Keycloak realm so Docs signs in on Drive's identity provider (single session across both apps).
|
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
| ) | ||
| item.soft_delete() | ||
| item.delete() | ||
| raise drf.exceptions.APIException(detail=str(exc)) from exc |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Purpose
POC exploring the integration of Docs into Drive: documents live in the Drive
tree next to regular files, and Drive becomes the source of truth for the
hierarchy, sharing and trash while Docs keeps owning content and collaborative
editing.
Proposal
metadata.external_apppoints to aresource hosted by another application. It has no filename and no physical
upload, is ready as soon as created, and can hold children (sub-documents).
File-only abilities (download, wopi, upload, convert) are disabled on them.
bearer token and act on behalf of a user via
X-User-Sub/X-User-Email,reusing every existing endpoint with its full permission logic. No identity
headers means the caller acts for an anonymous visitor, so public link reach
works end to end. The
"s2s"auth tag prevents notification loops.EXTERNAL_APPSprovidea backend implementing create/delete/restore/purge of their resources.
Integrating a new app does not require touching the item views. Docs is the
first implementation.
app back-channel (rolled back on failure); trash, restore and purge notify
the app for every pointer of the affected subtree, with an idempotent
backstop in the purge task covering the cron path.
surfaces), a
tree-descendantsaction serves the whole document tree to theapp, and the explorer gets a "New Docs document" entry; clicking a pointer
item (or landing on its preview route) opens the Docs frontend.
The Docs side of the POC lives in a companion branch on the impress
repository.
Notes
env.d/development/commonandan
impressclient in the Keycloak realm so both apps share the sameidentity provider.