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

For testing functionality, I recommend using the adjacent PR that adds it to the Dev Playground ( #114 ), I split PR so code is easier to review here.

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>

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

… docs, remove redundancy

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

…anifest

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

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

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

pkosiec · 2026-02-24T11:05:02Z

docs/docs/plugins.md

 - `format: "JSON"` (default) returns JSON rows
 - `format: "ARROW"` returns an Arrow "statement_id" payload over SSE, then the client fetches binary Arrow from `/api/analytics/arrow-result/:jobId`

+### Files plugin


Just a heads-up - no changes needed for now: I split the plugins.md into multiple files here: #126

Not sure which PR will get merged first, probably yours, so of course I'll update the docs to split the files into a dedicated document 👍

oh great! I was thinking about doing it on a follow-up PR as well 🏆

pkosiec · 2026-02-24T11:08:59Z

apps/dev-playground/server/index.ts

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


Do we need to pass the DATABRICKS_DEFAULT_VOLUME env value if it is already read by the plugin itself (at least that's what the plugin manifest says)? Looks redundant unless I'm missing something 🤔

pkosiec · 2026-02-24T11:09:53Z

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

+          host: "127.0.0.1",
+          autoStart: false,
+        }),
+        files({ defaultVolume: "/Volumes/catalog/schema/vol" }),


should it be empty if we set up the DATABRICKS_DEFAULT_VOLUME env?

Suggested change

files({ defaultVolume: "/Volumes/catalog/schema/vol" }),

files(),

?

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

fjakobs

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

fjakobs · 2026-02-24T16:18:33Z

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

-          totalSpend: number;
-          /** @sqlType DATE */
-          createdAt: string;
+          ;


the reverted types look like a regression

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?

fjakobs · 2026-02-24T16:59:23Z

docs/docs/plugins.md

+
+Routes are mounted at `/api/files/*`.
+
+#### Configuration


I see to problems with the proposed API:

We only support a single volume. We have no way of serving files from multiple vlumes

We have no access control. The API suggests that every user can read, delete, upload every file and upload to every.

I've tried to address this in my PoC like this:

https://github.com/databricks/appkit/pull/6/changes#diff-9d086cc651399510c1379ba2b4fee6aaa060fb066f4d190cb97b5be7a5a47facR18-R43

cc @MarioCadenas

fjakobs · 2026-02-24T17:00:24Z

docs/docs/plugins.md

+});
+```
+
+#### User-scoped operations in a route handler


how do these work?

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.

atilafassina and others added 14 commits February 20, 2026 11:07

chore: first draft

6f76009

chore: add files route to dev-playground

ce82860

chore: add injectRoutes logic to plugin

be66fdd

feat: add stream and cache

b27e231

chore: file upload stream

ece130a

chore: deduplicate tests, cleanup

5d85548

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

5b0a682

chore: remove dev-playground files integration

a1c05c4

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: update

91367c2

chore: cleanup integration tests

da0e62f

fix: add file resource to manifest

09f86c3

refactor: move client to /connectors

79bd173

chore: improve preview and MIME checks

f4826dc

chore: fix merge conflicts

60b1bcd

atilafassina force-pushed the plugin/files branch from 8fa2314 to 60b1bcd Compare February 20, 2026 10:25

docs: update

5200066

atilafassina force-pushed the plugin/files branch 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 added 2 commits February 20, 2026 16:10

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

a0dda75

… docs, remove redundancy

fix: xss vulnerability on raw serving files

b95711f

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

chore: linter warnings

1c5805b

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

fix: docs generation

e5e973d

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

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

bb57226

…anifest

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

clean up JSDoc

07b6671

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

Copilot AI reviewed Feb 23, 2026

View reviewed changes

atilafassina added 2 commits February 23, 2026 18:08

docs: format / cleanup

e065cdc

fix: edge case on extension matching / add tests

34ef4a5

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

fix: defaults variable naming

a99997f

	files({ defaultVolume: "/Volumes/catalog/schema/vol" }),
	files(),

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!

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

atilafassina commented Feb 18, 2026 •

edited

Loading

pkosiec left a comment •

edited

Loading