feat: Files Plugin by atilafassina · Pull Request #115 · databricks/appkit

atilafassina · 2026-02-18T16:16:54Z

This PR implements a first version of the Files API plugin according to the internal RFC.

Features

Important

this PR also touches the server plugin to bypass the express.json middleware for upload routes, otherwise the stream does not passthrough

Copilot

Pull request overview

This PR introduces a comprehensive Files plugin for AppKit that enables Unity Catalog volume file operations. The plugin provides both HTTP routes and a programmatic API for common file operations including list, read, download, upload, delete, and preview. It integrates with AppKit's execution interceptor pipeline for caching, retry, and timeout handling.

The PR also modifies the server plugin to support bypassing JSON body parsing for specific routes (needed for file upload streaming), introducing a new skipBodyParsing route configuration option and getSkipBodyParsingPaths() plugin interface method.

Changes:

New Files plugin with full CRUD operations for Unity Catalog volumes
Server plugin modification to support raw body streaming for file uploads
Comprehensive test coverage including unit, integration, and connector tests
Documentation updates including README, API docs, and plugin guide

Reviewed changes

Copilot reviewed 32 out of 33 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
`packages/appkit/src/plugins/files/plugin.ts`	Main FilesPlugin class with HTTP routes and programmatic API
`packages/appkit/src/plugins/files/types.ts`	TypeScript type definitions for file operations
`packages/appkit/src/plugins/files/defaults.ts`	Execution defaults for different operation tiers (read/download/write)
`packages/appkit/src/plugins/files/manifest.json`	Plugin manifest declaring resource requirements
`packages/appkit/src/connectors/files/client.ts`	FilesConnector implementing core file operations with telemetry
`packages/appkit/src/connectors/files/defaults.ts`	Content-type resolution and text detection helpers
`packages/appkit/src/plugins/server/index.ts`	Modified to support selective body parsing bypass
`packages/shared/src/plugin.ts`	Added `getSkipBodyParsingPaths()` to BasePlugin interface
`packages/appkit/src/plugin/plugin.ts`	Implementation of skipBodyParsing tracking and path registration
`packages/appkit/src/plugins/files/tests/*`	Comprehensive test suites for plugin, connector, and integration
`packages/appkit/src/plugins/server/tests/server.test.ts`	Tests for body parsing bypass functionality
`docs/docs/plugins.md`	Plugin guide with Files plugin documentation and examples
`packages/appkit/src/index.ts`	Export of files plugin and contentTypeFromPath helper
`apps/dev-playground/server/index.ts`	Dev playground integration

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

packages/appkit/src/plugins/files/README.md

docs/docs/plugins.md

packages/appkit/src/connectors/files/client.ts

packages/appkit/src/plugins/files/plugin.ts

packages/appkit/src/connectors/files/client.ts

docs/docs/plugins.md

Copilot

Pull request overview

Copilot reviewed 32 out of 33 changed files in this pull request and generated 7 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

apps/dev-playground/server/index.ts

packages/appkit/src/plugins/files/plugin.ts

Copilot

Pull request overview

Copilot reviewed 32 out of 32 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

packages/appkit/src/connectors/files/defaults.ts

packages/appkit/src/plugins/files/plugin.ts

packages/appkit/src/connectors/files/defaults.ts

packages/appkit/src/plugins/server/index.ts

Copilot

Pull request overview

Copilot reviewed 32 out of 32 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

pkosiec

The plugin looks awesome, great work! 👌
Could you please record a short demo how it works with the databricks apps init command and whether the apps deploy passes? Thanks in advance!

# in cli repo
make build
sudo ln -s "$(pwd)/cli" /usr/local/bin/dbx

# in appkit repo
DATABRICKS_APPKIT_TEMPLATE_PATH="/Users/pawel.kosiec/repositories/databricks-os/appkit/template" dbx apps init

docs/docs/plugins.md

apps/dev-playground/server/index.ts

packages/appkit/src/plugins/files/tests/plugin.integration.test.ts

packages/appkit/src/plugins/files/defaults.ts

fjakobs

Blocking - we need to solve access control before we can merge it

apps/dev-playground/client/src/appKitTypes.d.ts

fjakobs · 2026-02-24T16:19:28Z

apps/dev-playground/server/index.ts

    telemetryExamples(),
    analytics({}),
    lakebaseExamples(),
+    files({ defaultVolume: process.env.DATABRICKS_DEFAULT_VOLUME }),


how to we manage permissions. Can all users read and upload all the files?

docs/docs/plugins.md

fjakobs · 2026-02-24T17:01:49Z

docs/docs/plugins.md

+| `GET`  | `/api/files/preview?path=`  | Get a file preview with text excerpt.                |
+| `POST` | `/api/files/upload?path=`   | Upload a file (stream the request body).             |
+| `POST` | `/api/files/mkdir`          | Create a directory (`{ path }` in body).             |
+| `POST` | `/api/files/delete`         | Delete a file or directory (`{ path }` in body).     |


We also need something like createSignedUrl() (see https://supabase.com/docs/reference/javascript/storage-from-createsignedurl) so we can download files that take longer than 60s to download.

apps/dev-playground/server/index.ts

docs/docs/plugins.md

MarioCadenas · 2026-02-26T15:19:46Z

packages/appkit/src/connectors/files/client.ts

+  private async traced<T>(
+    operation: string,
+    attributes: Record<string, string>,
+    fn: (span: Span) => Promise<T>,
+  ): Promise<T> {
+    const startTime = Date.now();
+    let success = false;
+
+    return this.telemetry.startActiveSpan(
+      `files.${operation}`,
+      {
+        kind: SpanKind.CLIENT,
+        attributes: {
+          "files.operation": operation,
+          ...attributes,
+        },
+      },
+      async (span: Span) => {
+        try {
+          const result = await fn(span);
+          success = true;
+          span.setStatus({ code: SpanStatusCode.OK });
+          return result;
+        } catch (error) {
+          span.recordException(error as Error);
+          span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: error instanceof Error ? error.message : String(error),
+          });
+          throw error;
+        } finally {
+          span.end();
+          const duration = Date.now() - startTime;
+          const metricAttrs = {
+            "files.operation": operation,
+            success: String(success),
+          };
+          this.telemetryMetrics.operationCount.add(1, metricAttrs);
+          this.telemetryMetrics.operationDuration.record(duration, metricAttrs);
+        }
+      },
+      { name: this.name, includePrefix: true },
+    );
+  }


this whole method seems like a nice abstraction we could have as a core part of plugins no? I see there are some files related stuff but maybe we could have something more generic as part of the core? Not blocking, just a suggestion / idea

MarioCadenas · 2026-02-26T15:26:52Z

packages/appkit/src/connectors/files/client.ts

+  volume(volumePath: string): FilesConnector {
+    return new FilesConnector({
+      defaultVolume: volumePath,
+      telemetry: false,
+      customContentTypes: this.customContentTypes,
+    });
+  }


why do we return a full new instance of the class?

packages/appkit/src/index.ts

packages/appkit/src/plugins/files/plugin.ts

Move dev-playground route and UI to a separate branch (plugin/files-playground). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: Atila Fassina <atila@fassina.eu>

… docs, remove redundancy

…anifest

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* feat: create gateway and inject user context to every handler * docs: update API references * fix: register volume in `app.yml` for dev-playground * docs: update Class Plugin * chore: add files route and UI to dev-playground (#114) * chore: add files route and UI to dev-playground Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: Atila Fassina <atila@fassina.eu> * docs: regen --------- Signed-off-by: Atila Fassina <atila@fassina.eu> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> * fix: url path when uploading files + error handling/logging * Update packages/appkit/src/plugins/files/plugin.ts Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * chore: address code review comments * chore: remove unused import * fix: cache TTL should be in seconds * test: add integration tests for Files plugin * refactor: remove OBO Gateway * feat: add rate-limiter for uploads, cleanup code * chore: address docs and type gen --------- Signed-off-by: Atila Fassina <atila@fassina.eu> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

MarioCadenas · 2026-03-03T17:57:43Z

packages/appkit/src/plugins/files/plugin.ts

+      list: this.list.bind(this),
+      /** Read a file as a string. */
+      read: this.read.bind(this),
+      /** Download a file as a readable stream. */
+      download: this.download.bind(this),
+      /** Check whether a file exists. */
+      exists: this.exists.bind(this),
+      /** Retrieve file metadata. */
+      metadata: this.metadata.bind(this),
+      /** Upload a file. */
+      upload: this.upload.bind(this),
+      /** Create a directory. */
+      createDirectory: this.createDirectory.bind(this),
+      /** Delete a file or directory. */
+      delete: this.delete.bind(this),
+      /** Get a file preview with text excerpt. */
+      preview: this.preview.bind(this),


we don't need to bind things (it doesn't harm, but appkit takes care of it already 😄 )

fjakobs

We need to re-work the way we are handling absolute paths. I'm not comfortable serving files from volumes that the user didn't explicitly configure.

fjakobs · 2026-03-04T12:13:20Z

docs/docs/plugins/files.md

+- Upload size limits with streaming enforcement
+- Automatic cache invalidation on write operations
+- Custom content type mappings
+- Per-user execution context (OBO)


not blocking: we need to test what happens when we hit the 60s request timeout.

fjakobs · 2026-03-04T12:14:39Z

docs/docs/plugins/files.md

+
+## HTTP routes
+
+Routes are mounted at `/api/files/*`. All routes except `/root` execute in user context via `asUser(req)`.


why is /root special?

fjakobs · 2026-03-04T12:15:45Z

docs/docs/plugins/files.md

+The `/raw` endpoint serves files inline for browser display but applies security headers:
+- `X-Content-Type-Options: nosniff`
+- `Content-Security-Policy: sandbox`
+- Unsafe content types (HTML, JS, SVG) are forced to download via `Content-Disposition: attachment`


why not do this for all mime types? Then it's clear that it is always a download link.

fjakobs · 2026-03-04T12:18:23Z

docs/docs/plugins/files.md

+
+Paths can be **absolute** or **relative**:
+
+- **Absolute** — starts with `/`, must begin with `/Volumes/` (e.g. `/Volumes/catalog/schema/vol/data.csv`)


does this mean that you can read files from volumes that are not explicitly configured?

I would prefer a model where we "mount" a folder in a volume into the app and no folder outside of this mount is accessible.

fjakobs · 2026-03-04T12:20:23Z

packages/appkit-ui/src/react/file-browser/directory-list.tsx

@@ -0,0 +1,131 @@
+import { AlertCircle, ArrowLeft, FileIcon } from "lucide-react";


the UI components look pretty straightforward. I wonder if they should rather be a skill instead of library code.

cc @arsenyinfo @MarioCadenas

fjakobs · 2026-03-04T12:22:58Z

packages/appkit/src/connectors/files/tests/client.test.ts

+        (async function* () {})(),
+      );
+
+      await connector.list(mockClient, "/Volumes/other/path");


I'd consider this behaviour a security bug.

We explicitly configure the plugin to use /Volumes/catalog/schema/vol but now we can also read files from other volumes.

I know that the end user still needs permissions to read these files on the other volume but it's very unexpected and might still not be desireable.

fjakobs · 2026-03-04T12:26:59Z

packages/appkit/src/connectors/files/client.ts

+    if (segments.some((s) => s === "..")) {
+      throw new Error('Path traversal ("../") is not allowed.');
+    }
+    if (filePath.startsWith("/")) {


we should not allow reading files that are not in one of the configured volumes. I'd drop support for absolute paths entirely.

Alternatively we would also have to check the next folder level and make sure it matches the configured folder.

fjakobs · 2026-03-04T12:28:37Z

packages/appkit/src/connectors/files/client.ts

+      const host = hostValue.startsWith("http")
+        ? hostValue
+        : `https://${hostValue}`;
+      const url = new URL(`/api/2.0/fs/files${resolvedPath}`, host);


Ideally this should go into the JS SDK but for now it's fine

atilafassina force-pushed the plugin/files branch 2 times, most recently from 744d776 to 5200066 Compare February 20, 2026 13:01

atilafassina marked this pull request as ready for review February 20, 2026 13:03

Copilot AI review requested due to automatic review settings February 20, 2026 13:03

Copilot started reviewing on behalf of atilafassina February 20, 2026 13:03 View session

Copilot AI reviewed Feb 20, 2026

View reviewed changes

atilafassina requested a review from Copilot February 20, 2026 15:30

Copilot started reviewing on behalf of atilafassina February 20, 2026 15:31 View session

atilafassina force-pushed the plugin/files branch from cd3d855 to 1c5805b Compare February 20, 2026 15:34

Copilot AI reviewed Feb 20, 2026

View reviewed changes

atilafassina requested a review from Copilot February 20, 2026 15:58

Copilot started reviewing on behalf of atilafassina February 20, 2026 15:59 View session

atilafassina force-pushed the plugin/files branch from e86e4a4 to bb57226 Compare February 20, 2026 16:03

atilafassina requested a review from MarioCadenas February 20, 2026 16:04

Copilot AI reviewed Feb 20, 2026

View reviewed changes

atilafassina requested a review from Copilot February 23, 2026 13:56

Copilot started reviewing on behalf of atilafassina February 23, 2026 13:56 View session

Copilot AI reviewed Feb 23, 2026

View reviewed changes

atilafassina requested a review from fjakobs February 23, 2026 17:30

pkosiec reviewed Feb 24, 2026

View reviewed changes

fjakobs requested changes Feb 24, 2026

View reviewed changes

MarioCadenas reviewed Feb 26, 2026

View reviewed changes

atilafassina and others added 8 commits March 3, 2026 17:27

chore: first draft

0eecae5

chore: add files route to dev-playground

7ec6cfc

chore: add injectRoutes logic to plugin

2d9ff0b

feat: add stream and cache

fd26204

chore: file upload stream

6a762f2

chore: deduplicate tests, cleanup

7863da0

chore: skip bail req.body type for specific routes in Server plugin

ad5f0a3

chore: remove dev-playground files integration

93acd0b

Move dev-playground route and UI to a separate branch (plugin/files-playground). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: Atila Fassina <atila@fassina.eu>

atilafassina and others added 19 commits March 3, 2026 17:37

chore: improve preview and MIME checks

f730f7d

docs: update

9c2465c

chore: address code-review, improve consistency across endpoints, fix…

fbb4090

… docs, remove redundancy

fix: xss vulnerability on raw serving files

4746216

chore: linter warnings

6d5bbb5

fix: docs generation

1f20611

chore: security in-depth and a few inconsistencies between docs and m…

3bb7ea4

…anifest

clean up JSDoc

f508164

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

docs: format / cleanup

e2276ce

fix: edge case on extension matching / add tests

2deb41c

fix: defaults variable naming

5a26523

chore: address code review with multiple small fixes

a89ab87

feat: ui-components

c368af6

chore: only passthrough 4xx errors

133852b

chore: revert typegen regression

35fcde6

chore: remove unnecessary export

1172704

fix: race condition on cache invalidation

47a201f

chore: improve security and cleanup code a bit more

4d1d69d

atilafassina force-pushed the plugin/files branch from e7ecbe6 to 4d1d69d Compare March 3, 2026 16:58

atilafassina requested a review from fjakobs March 3, 2026 17:12

atilafassina added 2 commits March 3, 2026 18:18

chore: linting and docs building

878d3c8

chore: last minute security concerns on validation and routes

9938c0c

MarioCadenas reviewed Mar 3, 2026

View reviewed changes

atilafassina added 4 commits March 3, 2026 19:02

chore: add docs back

fd5e8fb

fix: do not pass-through errors from the API

875235c

chore: adjust unit tests

d08f74b

docs: update

e6747f1

MarioCadenas approved these changes Mar 4, 2026

View reviewed changes

fjakobs requested changes Mar 4, 2026

View reviewed changes


		## HTTP routes

		Routes are mounted at `/api/files/*`. All routes except `/root` execute in user context via `asUser(req)`.


		Paths can be absolute or relative:

		- Absolute — starts with `/`, must begin with `/Volumes/` (e.g. `/Volumes/catalog/schema/vol/data.csv`)

		@@ -0,0 +1,131 @@
		import { AlertCircle, ArrowLeft, FileIcon } from "lucide-react";

Conversation

atilafassina commented Feb 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Features

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

pkosiec left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fjakobs left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fjakobs left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

atilafassina commented Feb 18, 2026 •

edited

Loading

pkosiec left a comment •

edited

Loading