Warning
Experimental. This is a prototype built to evaluate resumable uploads for FrankenPHP. The configuration, the hook format and the module path may change or disappear without notice. Do not use it in production.
A Caddy HTTP handler that serves resumable uploads with tusd, the reference implementation of the tus protocol. It also accepts the IETF Resumable Uploads draft, up to draft -05 (see Limitations).
Uploads are written to disk by Caddy, so slow clients never hold a PHP thread.
PHP only runs for short hooks: authorizing an upload before it starts, and processing the stored file once it is complete.
Hooks are internal sub-requests sent to the next handler (typically php_server), with the client's cookies and headers, so sessions and auth work as usual.
With xcaddy and stock Caddy:
xcaddy build --with github.com/dunglas/caddy-tusWith FrankenPHP, add --with github.com/dunglas/caddy-tus to the FrankenPHP xcaddy command.
cmd/frankenphp-tus is a ready-made FrankenPHP build including this module:
cd cmd/frankenphp-tus
CGO_ENABLED=1 \
CGO_CFLAGS="$(php-config --includes)" \
CGO_LDFLAGS="$(php-config --ldflags) $(php-config --libs)" \
go build -tags=nobadger,nomysql,nopgx -o ../../frankenphp-tus .{
frankenphp
}
example.com {
root public
tus {
base_path /files/
dir /var/lib/uploads
max_size 1GB
ietf_draft
hook_uri /tus-hook.php
hooks pre-create pre-finish
}
php_server {
# Set only on hook sub-requests, clients cannot forge it.
env TUS_HOOK {http.vars.tus_hook}
}
}| Subdirective | Description |
|---|---|
base_path |
URL prefix of the upload endpoint. Default: /files/ |
dir |
Directory where uploads are stored (required) |
max_size |
Maximum upload size, e.g. 1GB. Default: unlimited |
ietf_draft |
Also accept the IETF Resumable Uploads draft |
enable_download |
Serve uploads with GET. Off by default: upload IDs are the only protection |
disable_termination |
Refuse DELETE |
hook_uri |
Path receiving hook sub-requests |
hooks |
Hooks sent to hook_uri: pre-create, pre-finish, pre-terminate. Default: pre-create pre-finish |
tus runs after basic_auth and forward_auth, so they also protect uploads.
Each hook is a POST to hook_uri with a JSON body in tusd's HTTP hook format:
{"Type": "pre-finish", "Event": {"Upload": {"ID": "...", "Size": 3000000, "MetaData": {}, "Storage": {"Path": "/var/lib/uploads/..."}}, "HTTPRequest": {}}}The Caddy variable tus_hook holds the hook type on hook sub-requests only.
Expose it to PHP with env TUS_HOOK {http.vars.tus_hook} and reject requests where it is empty: the hook script is otherwise reachable by anyone.
Responses:
- A non-2xx response rejects the operation and is sent to the client as is:
http_response_code(401)is enough to refuse an upload. - An empty 2xx r 791D esponse accepts it.
- A JSON body is read as tusd's hook response:
RejectUpload,ChangeFileInfo(e.g. rewrite metadata),HTTPResponse(headers and body added to the client response).
<?php
if (empty($_SERVER['TUS_HOOK'])) {
http_response_code(404);
exit;
}
$hook = json_decode(file_get_contents('php://input'), true, flags: JSON_THROW_ON_ERROR);
$upload = $hook['Event']['Upload'];
switch ($_SERVER['TUS_HOOK']) {
case 'pre-create':
session_start();
if (!isset($_SESSION['user'])) {
http_response_code(401);
}
break;
case 'pre-finish':
// The file is complete: move it, scan it, store a reference...
rename($upload['Storage']['Path'], '/srv/files/'.$upload['ID']);
break;
}A complete example with an end-to-end curl test lives in example.
- IETF draft: tusd supports interop versions 3 to 6 (drafts -01 to -05). The current draft (-15) uses interop version 10; such clients get
412 Precondition Failed. pre-finishruns at most once: if the hook fails, the upload stays complete and a retriedPATCHdoes not call it again (tus/tusd#1299).- No access hook: PHP authorizes upload creation only. Later requests on an upload are protected by its random ID and by any Caddy auth in front.
- Synchronous hooks only: post-finish and other asynchronous hooks are not supported.
- Filesystem storage only: no S3, no distributed locking, no expiration of abandoned uploads.
The full investigation, including the comparison with a FrankenPHP extension, is in docs/investigation.md.
MIT