Theme
Event handlers Preview
An event handler runs a script when a file event fires.
This page is the console. The events have their own reference
The fields and buttons are here. What each event carries, exactly when it fires and what a script can read from it is on Events and when they fire.
Two families:
- Before events run in front of the operation and can block it.
- After events observe an operation that has already happened and cannot undo it.
Creating one
Automation, then Event handlers, then New event handler. You need a script first.
| Field | Notes |
|---|---|
| Name | Yours |
| Event | Which event fires it |
| Script | Which script it runs |
| Applies to | Everything, or one virtual file system |
| Priority | Lower runs first when several handlers share an event |
| Timeout (ms) | Bounds this handler's run. Default 5000 |
| If the script fails or times out | Block the operation, or let it proceed |
| Run in the background | After events only. Does not delay the operation |
| Enabled | A disabled handler never runs |
Saving applies immediately. No restart.
The events
The id column is what EventHandler() returns inside a script, and what appears in the log.
| Event | id | Fires |
|---|---|---|
| Before a file is uploaded | before.upload | When a file is opened for writing |
| After a file is uploaded | after.upload | When the uploaded file is closed, not when it opens |
| Before a file is downloaded | before.download | When a file is opened for reading |
| After a file is downloaded | after.download | When the downloaded file is closed |
| Before a file is deleted | before.delete | |
| After a file is deleted | after.delete | |
| Before a folder is deleted | before.deleteDir | |
| After a folder is deleted | after.deleteDir | |
| Before a rename or move | before.rename | |
| After a rename or move | after.rename | |
| Before a folder is created | before.makeDir | |
| After a folder is created | after.makeDir | |
| Before a folder is listed | before.listDir | |
| After a folder is listed | after.listDir | |
| Before a transfer to another storage | before.transfer | When the Head asks this Connector to copy or move a file into another of its virtual file systems |
| After a transfer to another storage | after.transfer | When that transfer has been written and verified |
| Filter a folder listing | dirList.filter | Lets a script hide entries from a listing |
| When a tunnel disconnects | session.disconnect | For cleanup. Carries no context at all |
Upload and download complete at close
The after upload and download events fire when the file closes, not when it opens, because only then is the content complete. A script bound to after upload can read the finished file.
Fail mode
If the script fails or times out:
| Choice | Effect |
|---|---|
| Block the operation | The operation is denied. The default for a before handler |
| Let the operation proceed | The failure is logged and the operation continues |
A before handler is a policy gate. Blocking on failure is the safe default: a gate that opens when it breaks is not a gate.
Set it to let the operation proceed while you are developing the script, and tighten it once the script behaves.
After handlers always let the operation proceed. The operation has already committed; there is nothing to block.
Priority
When several handlers are bound to the same event, lower priority runs first.
On a before event, the first handler that refuses stops the chain: later handlers do not run.
Scope
Everything binds the handler to every virtual file system on this Connector.
One virtual file system binds it to one.
A scoped handler never sees a disconnect
When a tunnel disconnects carries no virtual file system name, so there is nothing for a scoped handler to match against and it does not fire. Bind disconnect handlers to Everything.
Start scoped. A handler bound to everything runs on every operation on the machine, including ones you were not thinking about when you wrote it.
Running in the background
An after handler can be marked to run in the background, so it does not delay the operation. Use this for anything slow: a webhook to another system, an antivirus submission, a database write.
A background handler's failures are logged and never surfaced to the user.
Filtering a folder listing
The Filter a folder listing event lets a script hide entries. Inside it:
js
Session.RemoveFromDirList("*.tmp");
Session.RemoveFromDirList(".DS_Store");Patterns are matched against the entry's name only, never the full path, and they are case sensitive. The syntax is *, ? and [range]; there is no **. A malformed pattern is skipped and the rest still apply.
A filter handler always runs synchronously; Run in the background is ignored there, because the answer is needed before the listing is sent. If the script fails or times out, the listing ships with whatever patterns had accumulated, and the listing is never blocked.
The entries are removed from what the user sees. This is a display filter, not a permission. A user who knows the exact name of a hidden file, and holds permission on it, can still open it. If something must be unreachable, do not grant it: see Permissions.
Deleting a handler
The handler is removed. Its script stays, and other handlers using it are unaffected.
Two worked examples
Refuse uploads of executables. A Before a file is uploaded handler, scoped to one virtual file system, fail mode Block the operation, running a script that calls Exit(1) for the extensions you refuse.
Notify another system after an upload. An After a file is uploaded handler, Run in the background on, running a script that posts the path and the username to your own endpoint. It never delays the transfer, and a failure never affects the user.
More examples
Complete scripts with the handler settings each one needs are on Worked examples.