LumeWeb
/
tusd
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Update hook structure

This commit is contained in:
Marius 2019-09-20 16:36:05 +02:00
parent e7dfc9405d
commit 46d2adcc12
1 changed files with 93 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

149
docs/hooks.md
View File

@ -61,55 +61,66 @@ $ tusd --hooks-dir ./path/to/hooks/
... ...
``` ```
If an event occurs, the tusd binary will look for a file, named exactly as the event, which will then be executed, as long as the object exists. In the example above, the binary `./path/to/hooks/pre-create` will be invoked, before an upload is created, which can be used to e.g. validate certain metadata. Please note, that in UNIX environments the hook file *must not* have an extension, such as `.sh` or `.py`, or else tusd will not recognize and ignore it. On Windows, however, the hook file *must* have an extension, such as `.bat` or `.exe`. A detailed list of all events can be found at the end of this document. If an event occurs, the tusd binary will look for a file, named exactly as the event, which will then be executed, as long as the object exists. In the example above, the binary `./path/to/hooks/pre-create` will be invoked, before an upload is created, which can be used to e.g. validate certain metadata. Please note, that in UNIX environments the hook file *must not* have an extension, such as `.sh` or `.py`, or else tusd will not recognize and ignore it. On Windows, however, the hook file *must* have an extension, such as `.bat` or `.exe`.
### The Hook's Environment ### The Hook's Environment
The process of the hook files are provided with information about the event and the upload using to two methods: The process of the hook files are provided with information about the event and the upload using to two methods:
* The `TUS_ID` and `TUS_SIZE` environment variables will contain the upload ID and its size in bytes, which triggered the event. Please be aware, that in the `pre-create` hook the upload ID will be an empty string as the entity has not been created and therefore this piece of information is not yet available. * The `TUS_ID` and `TUS_SIZE` environment variables will contain the upload ID and its size in bytes, which triggered the event. Please be aware, that in the `pre-create` hook the upload ID will be an empty string as the entity has not been created and therefore this piece of information is not yet available.
* On `stdin` a JSON-encoded object can be read which contains more details about the corresponding upload in following format: * On `stdin` a JSON-encoded object can be read which contains more details about the corresponding event in following format:
```js ```js
{ {
// The upload's ID. Will be empty during the pre-create event // The upload object contains the upload's details
"ID": "14b1c4c77771671a8479bc0444bbc5ce", "Upload": {
// The upload's total size in bytes. // The upload's ID. Will be empty during the pre-create event
"Size": 46205, "ID": "14b1c4c77771671a8479bc0444bbc5ce",
// The upload's current offset in bytes. // The upload's total size in bytes.
"Offset": 1592, "Size": 46205,
// These properties will be set to true, if the upload as a final or partial // The upload's current offset in bytes.
// one. See the Concatenation extension for details: "Offset": 1592,
// http://tus.io/protocols/resumable-upload.html#concatenation // These properties will be set to true, if the upload as a final or partial
"IsFinal": false, // one. See the Concatenation extension for details:
"IsPartial": false, // http://tus.io/protocols/resumable-upload.html#concatenation
// If the upload is a final one, this value will be an array of upload IDs "IsFinal": false,
// which are concatenated to produce the upload. "IsPartial": false,
"PartialUploads": null, // If the upload is a final one, this value will be an array of upload IDs
// The upload's meta data which can be supplied by the clients as it wishes. // which are concatenated to produce the upload.
// All keys and values in this object will be strings. "PartialUploads": null,
// Be aware that it may contain maliciously crafted values and you must not // The upload's meta data which can be supplied by the clients as it wishes.
// trust it without escaping it first! // All keys and values in this object will be strings.
"MetaData": { // Be aware that it may contain maliciously crafted values and you must not
"filename": "transloadit.png" // trust it without escaping it first!
}, "MetaData": {
// Details about where the data store saved the uploaded file. The different "filename": "transloadit.png"
// availabl keys vary depending on the used data store. },
"Storage": { // Details about where the data store saved the uploaded file. The different
// For example, the filestore supplies the absolute file path: // availabl keys vary depending on the used data store.
"Type": "filestore", "Storage": {
"Path": "/my/upload/directory/14b1c4c77771671a8479bc0444bbc5ce", // For example, the filestore supplies the absolute file path:
"Type": "filestore",
"Path": "/my/upload/directory/14b1c4c77771671a8479bc0444bbc5ce",
// The S3Store and GCSStore supply the bucket name and object key: // The S3Store and GCSStore supply the bucket name and object key:
"Type": "s3store", "Type": "s3store",
"Bucket": "my-upload-bucket", "Bucket": "my-upload-bucket",
"Key": "my-prefix/14b1c4c77771671a8479bc0444bbc5ce" "Key": "my-prefix/14b1c4c77771671a8479bc0444bbc5ce"
}
},
// Details about the HTTP request which caused this hook to be fired.
// It can be used to record the client's IP address or inspect the headers.
"HTTPRequest": {
"Method": "PATCH",
"URI": "/files/14b1c4c77771671a8479bc0444bbc5ce",
"RemoteAddr": "1.2.3.4:47689",
"Header": {
"Host": "myuploads.net",
"Cookies": "..."
}
} }
} }
``` ```
Be aware that this environment does *not* contain direct data from any HTTP request, in particular not any header values or cookies. If you would like to pass information from the client to the hook, such as authentication details, you may wish to use the [metadata system](http://tus.io/protocols/resumable-upload.html#upload-metadata).
## HTTP Hooks ## HTTP Hooks
HTTP Hooks are the second type of hooks supported by tusd. Like the file hooks, it is disabled by default. To enable it, pass the `--hooks-http` option to the tusd binary. The flag's value will be an HTTP URL endpoint, which the tusd binary will issue POST requests to: HTTP Hooks are the second type of hooks supported by tusd. Like the file hooks, it is disabled by default. To enable it, pass the `--hooks-http` option to the tusd binary. The flag's value will be an HTTP URL endpoint, which the tusd binary will issue POST requests to:
@ -133,26 +144,52 @@ Tusd will issue a `POST` request to the specified URL endpoint, specifying the h
```js ```js
{ {
// The upload's ID. Will be empty during the pre-create event // The upload object contains the upload's details
"ID": "14b1c4c77771671a8479bc0444bbc5ce", "Upload": {
// The upload's total size in bytes. // The upload's ID. Will be empty during the pre-create event
"Size": 46205, "ID": "14b1c4c77771671a8479bc0444bbc5ce",
// The upload's current offset in bytes. // The upload's total size in bytes.
"Offset": 1592, "Size": 46205,
// These properties will be set to true, if the upload as a final or partial // The upload's current offset in bytes.
// one. See the Concatenation extension for details: "Offset": 1592,
// http://tus.io/protocols/resumable-upload.html#concatenation // These properties will be set to true, if the upload as a final or partial
"IsFinal": false, // one. See the Concatenation extension for details:
"IsPartial": false, // http://tus.io/protocols/resumable-upload.html#concatenation
// If the upload is a final one, this value will be an array of upload IDs "IsFinal": false,
// which are concatenated to produce the upload. "IsPartial": false,
"PartialUploads": null, // If the upload is a final one, this value will be an array of upload IDs
// The upload's meta data which can be supplied by the clients as it wishes. // which are concatenated to produce the upload.
// All keys and values in this object will be strings. "PartialUploads": null,
// Be aware that it may contain maliciously crafted values and you must not // The upload's meta data which can be supplied by the clients as it wishes.
// trust it without escaping it first! // All keys and values in this object will be strings.
"MetaData": { // Be aware that it may contain maliciously crafted values and you must not
"filename": "transloadit.png" // trust it without escaping it first!
"MetaData": {
"filename": "transloadit.png"
},
// Details about where the data store saved the uploaded file. The different
// availabl keys vary depending on the used data store.
"Storage": {
// For example, the filestore supplies the absolute file path:
"Type": "filestore",
"Path": "/my/upload/directory/14b1c4c77771671a8479bc0444bbc5ce",
// The S3Store and GCSStore supply the bucket name and object key:
"Type": "s3store",
"Bucket": "my-upload-bucket",
"Key": "my-prefix/14b1c4c77771671a8479bc0444bbc5ce"
}
},
// Details about the HTTP request which caused this hook to be fired.
// It can be used to record the client's IP address or inspect the headers.
"HTTPRequest": {
"Method": "PATCH",
"URI": "/files/14b1c4c77771671a8479bc0444bbc5ce",
"RemoteAddr": "1.2.3.4:47689",
"Header": {
"Host": "myuploads.net",
"Cookies": "..."
}
} }
} }
``` ```