Merge pull request #45 from tus/hooks

Hooks

Author: bhstahl

README.md

@@ -81,6 +81,58 @@ app.all('/files/*', function(req, res) {
 app.listen(port, host);
 ```
 
+## Event Hooks
+
+Execute code when lifecycle events happen by adding event handlers to your server.
+
+```js
+const Server = require('tus-node-server').Server;
+const EVENTS = require('tus-node-server').EVENTS;
+
+const server = new Server();
+server.on(EVENTS.EVENT_UPLOAD_COMPLETE, (event) => {
+    console.log(`[${new Date().toLocaleTimeString()}] [EVENT HOOK] Upload complete for file ${event.file.id}`);
+    console.log(event);
+});
+```
+
+#### Events:
+
+- `EVENT_FILE_CREATED`: Fired when a `POST` request successfully creates a new file
+
+    _Example payload:_
+    ```
+    {
+        file: {
+            id: '7b26bf4d22cf7198d3b3706bf0379794',
+            upload_length: '41767441',
+            upload_metadata: 'filename NDFfbWIubXA0'
+         }
+    }
+    ```
+
+- `EVENT_ENDPOINT_CREATED`: Fired when a `POST` request successfully creates a new upload endpoint
+
+    _Example payload:_
+    ```
+    {
+        url: 'http://localhost:8000/files/7b26bf4d22cf7198d3b3706bf0379794'
+    }
+    ```
+
+- `EVENT_UPLOAD_COMPLETE`: Fired when a `PATCH` request finishes writing the file.
+
+    _Example payload:_
+    ```
+    {
+        file: {
+            id: '7b26bf4d22cf7198d3b3706bf0379794',
+            upload_length: '41767441',
+            upload_metadata: 'filename NDFfbWIubXA0'
+        }
+    }
+    ```
+
 ## Development
 
 Start the demo server using Local File Storage

demo/server.js

@@ -1,16 +1,20 @@
 'use strict';
 
-const tus = require('../index');
 const path = require('path');
 const fs = require('fs');
 
-const server = new tus.Server();
+const Server = require('../index').Server;
+const FileStore = require('../index').FileStore;
+const GCSDataStore = require('../index').GCSDataStore;
+const EVENTS = require('../index').EVENTS;
+
+const server = new Server();
 
 const data_store = process.env.DATA_STORE || 'FileStore';
 
 switch (data_store) {
     case 'GCSDataStore':
-        server.datastore = new tus.GCSDataStore({
+        server.datastore = new GCSDataStore({
             path: '/files',
             projectId: 'vimeo-open-source',
             keyFilename: path.resolve(__dirname, '../test/keyfile.json'),
@@ -19,7 +23,7 @@ switch (data_store) {
         break;
 
     default:
-        server.datastore = new tus.FileStore({
+        server.datastore = new FileStore({
             path: '/files',
         });
 }
@@ -52,6 +56,10 @@ server.get('/', writeFile);
 server.get('/demo/index.js', writeFile);
 server.get('/node_modules/tus-js-client/dist/tus.js', writeFile);
 
+server.on(EVENTS.EVENT_UPLOAD_COMPLETE, (event) => {
+    console.log(`[${new Date().toLocaleTimeString()}] [EVENT HOOK] Upload complete for file ${event.file.id}`);
+});
+
 const host = '127.0.0.1';
 const port = 8000;
 server.listen({ host, port }, () => {

index.js

@@ -4,10 +4,12 @@ const Server = require('./lib/Server');
 const DataStore = require('./lib/stores/DataStore');
 const FileStore = require('./lib/stores/FileStore');
 const GCSDataStore = require('./lib/stores/GCSDataStore');
+const EVENTS = require('./lib/constants').EVENTS;
 
 module.exports = {
     Server,
     DataStore,
     FileStore,
     GCSDataStore,
+    EVENTS,
 };

lib/Server.js

@@ -7,6 +7,7 @@
  * @author Ben Stahl <[email protected]>
  */
 const http = require('http');
+const EventEmitter = require('events');
 
 const DataStore = require('./stores/DataStore');
 const HeadHandler = require('./handlers/HeadHandler');
@@ -16,15 +17,37 @@ const PostHandler = require('./handlers/PostHandler');
 const RequestValidator = require('./validators/RequestValidator');
 
 const EXPOSED_HEADERS = require('./constants').EXPOSED_HEADERS;
+const REQUEST_METHODS = require('./constants').REQUEST_METHODS;
 const TUS_RESUMABLE = require('./constants').TUS_RESUMABLE;
 
-class TusServer {
+class TusServer extends EventEmitter {
 
     constructor() {
+        super();
+
         // Any handlers assigned to this object with the method as the key
         // will be used to repond to those requests. They get set/re-set
         // when a datastore is assigned to the server.
         this.handlers = {};
+
+        // Remove any event listeners from each handler as they are removed
+        // from the server. This must come before adding a 'newListener' listener,
+        // to not add a 'removeListener' event listener to all request handlers.
+        this.on('removeListener', (event, listener) => {
+            this.datastore.removeListener(event, listener);
+            REQUEST_METHODS.forEach((method) => {
+                this.handlers[method].removeListener(event, listener);
+            });
+        });
+
+        // As event listeners are added to the server, make sure they are
+        // bubbled up from request handlers to fire on the server level.
+        this.on('newListener', (event, listener) => {
+            this.datastore.on(event, listener);
+            REQUEST_METHODS.forEach((method) => {
+                this.handlers[method].on(event, listener);
+            });
+        });
     }
 
     /**

lib/constants.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const METHODS = [
+const REQUEST_METHODS = [
     'POST',
     'HEAD',
     'PATCH',
@@ -59,14 +59,29 @@ const ERRORS = {
     },
 };
 
+const EVENT_ENDPOINT_CREATED = 'EVENT_ENDPOINT_CREATED';
+const EVENT_FILE_CREATED = 'EVENT_FILE_CREATED';
+const EVENT_UPLOAD_COMPLETE = 'EVENT_UPLOAD_COMPLETE';
+
+const EVENTS = {
+    EVENT_ENDPOINT_CREATED,
+    EVENT_FILE_CREATED,
+    EVENT_UPLOAD_COMPLETE,
+};
+
 module.exports = {
-    TUS_RESUMABLE: '1.0.0',
-    TUS_VERSION: ['1.0.0'],
-    HEADERS,
-    HEADERS_LOWERCASE,
-    ALLOWED_METHODS: METHODS.join(', '),
     ALLOWED_HEADERS: HEADERS.join(', '),
+    ALLOWED_METHODS: REQUEST_METHODS.join(', '),
+    ERRORS,
+    EVENT_ENDPOINT_CREATED,
+    EVENT_FILE_CREATED,
+    EVENT_UPLOAD_COMPLETE,
+    EVENTS,
     EXPOSED_HEADERS: HEADERS.join(', '),
+    HEADERS,
+    HEADERS_LOWERCASE,
     MAX_AGE: 86400,
-    ERRORS,
+    REQUEST_METHODS,
+    TUS_RESUMABLE: '1.0.0',
+    TUS_VERSION: ['1.0.0'],
 };

lib/handlers/BaseHandler.js

@@ -1,9 +1,12 @@
 'use strict';
 
 const DataStore = require('../stores/DataStore');
+const EventEmitter = require('events');
 
-class BaseHandler {
+
+class BaseHandler extends EventEmitter {
     constructor(store) {
+        super();
         if (!(store instanceof DataStore)) {
             throw new Error(`${store} is not a DataStore`);
         }

lib/handlers/PostHandler.js

@@ -2,6 +2,7 @@
 
 const BaseHandler = require('./BaseHandler');
 const ERRORS = require('../constants').ERRORS;
+const EVENT_ENDPOINT_CREATED = require('../constants').EVENT_ENDPOINT_CREATED;
 
 class PostHandler extends BaseHandler {
     /**
@@ -15,6 +16,7 @@ class PostHandler extends BaseHandler {
         return this.store.create(req)
             .then((File) => {
                 const url = `http://${req.headers.host}${this.store.path}/${File.id}`;
+                this.emit(EVENT_ENDPOINT_CREATED, { url });
                 return super.send(res, 201, { Location: url });
             })
             .catch((error) => {

lib/stores/DataStore.js

@@ -9,10 +9,13 @@
 
 const Uid = require('../models/Uid');
 const File = require('../models/File');
+const EventEmitter = require('events');
 const ERRORS = require('../constants').ERRORS;
+const EVENTS = require('../constants').EVENTS;
 
-class DataStore {
+class DataStore extends EventEmitter {
     constructor(options) {
+        super();
         if (!options || !options.path) {
             throw new Error('Store must have a path');
         }
@@ -59,6 +62,7 @@ class DataStore {
             const file_id = this.generateFileName(req);
             const file = new File(file_id, upload_length, upload_defer_length, upload_metadata);
 
+            this.emit(EVENTS.EVENT_FILE_CREATED, { file });
             return resolve(file);
         });
     }
@@ -78,6 +82,8 @@ class DataStore {
         return new Promise((resolve, reject) => {
             // Stub resolve for tests
             const offset = 0;
+
+            this.emit(EVENTS.EVENT_UPLOAD_COMPLETE, { file: null });
             return resolve(offset);
         });
     }
@@ -95,6 +101,7 @@ class DataStore {
             if (!id) {
                 return reject(ERRORS.FILE_NOT_FOUND);
             }
+
             return resolve({ size: 0, upload_length: 1 });
         });
     }

lib/stores/FileStore.js

@@ -9,6 +9,7 @@ const MASK = '0777';
 const IGNORED_MKDIR_ERROR = 'EEXIST';
 const FILE_DOESNT_EXIST = 'ENOENT';
 const ERRORS = require('../constants').ERRORS;
+const EVENTS = require('../constants').EVENTS;
 
 
 /**
@@ -82,6 +83,7 @@ class FileStore extends DataStore {
                         return reject(exception);
                     }
 
+                    this.emit(EVENTS.EVENT_FILE_CREATED, { file });
                     return resolve(file);
                 });
             });
@@ -115,6 +117,11 @@ class FileStore extends DataStore {
                 console.info(`[FileStore] write: ${new_offset} bytes written to ${path}`);
                 offset += new_offset;
                 console.info(`[FileStore] write: File is now ${offset} bytes`);
+
+                const config = this.configstore.get(file_id);
+                if (config && parseInt(config.upload_length, 10) === new_offset) {
+                    this.emit(EVENTS.EVENT_UPLOAD_COMPLETE, { file: config });
+                }
                 resolve(offset);
             });
 

lib/stores/GCSDataStore.js

@@ -6,6 +6,7 @@ const gcloud = require('google-cloud');
 const assign = require('object-assign');
 const stream = require('stream');
 const ERRORS = require('../constants').ERRORS;
+const EVENTS = require('../constants').EVENTS;
 const TUS_RESUMABLE = require('../constants').TUS_RESUMABLE;
 const DEFAULT_CONFIG = {
     scopes: ['https://www.googleapis.com/auth/devstorage.full_control'],
@@ -107,6 +108,7 @@ class GCSDataStore extends DataStore {
             fake_stream.pipe(gcs_file.createWriteStream(options))
             .on('error', reject)
             .on('finish', () => {
+                this.emit(EVENTS.EVENT_FILE_CREATED, { file });
                 resolve(file);
             });
         });
@@ -153,6 +155,11 @@ class GCSDataStore extends DataStore {
 
                 req.on('end', () => {
                     console.log(`${new_offset} bytes written`);
+
+                    if (data.upload_length === new_offset) {
+                        this.emit(EVENTS.EVENT_UPLOAD_COMPLETE, { file });
+                    }
+
                     resolve(new_offset);
                 });