API - SCWorker
The SCWorker should be instantiated inside the worker controller file (worker.js). The worker controller is the entry point for your application logic.
Example worker controller:
var SCWorker = require('socketcluster/scworker');
class Worker extends SCWorker {
// Override the run function.
// It will be executed when the worker is ready.
run() {
this.scServer.on('connection', function (socket) {
// Handle new connection.
}
}
// You can optionally override the createHTTPServer method if
// you want to provide an alternative HTTP server to SC.
// This is for advanced use cases.
createHTTPServer() {
var httpServer;
if (this.options.protocol == 'https') {
httpServer = require('https').createServer(this.options.protocolOptions);
} else {
httpServer = require('http').createServer();
}
return httpServer;
}
}
new Worker();
Inherits from:
Properties:
| id | The id is an index - The first worker's id will always be 0. |
| isLeader | Boolean which indicates whether or not this worker is the leader (id == 0). |
| options | The options object passed to this worker from master. |
| httpServer | The Node.js HTTP server associated with this worker. Note that this server's 'request' event will not trigger for requests which are handled internally by SocketCluster. If you would like to handle all requests (including ones for URLs reserved by SC), you will need to listen for the 'rawRequest' event. This is not recommended though unless you know what you're doing. |
| scServer | The SCServer instance associated with this worker. |
| exchange | A top-level scBroker client which lets you publish and manipulate data within your brokers. (See API section on Exchange object for details). |
| auth | The current AuthEngine used by SC (this is what SC uses internally to create/sign and verify auth tokens). |
Events:
| 'error' | This gets triggered when fatal error occurs on this worker. |
| 'notice' | A notice carries potentially useful information but isn't quite an error. |
| 'exit' | Happens when this worker exits (sometimes due to error). |
| 'ready' | This signals that the worker is ready to accept requests from users. |
| 'masterMessage' |
Emitted when the master process sends a message to this worker.
Since SocketCluster version 6.6.0, the handler function accepts two arguments; the first is the data which was sent
by the master process, the second is a respond callback function which you can call to respond to the
event using IPC. The respond function should be invoked as respond(error, data); it is recommended
that you pass an instance of the Error object as the first argument; if you don't want to send back an error,
then the first argument should be null: respond(null, data).
See sendToWorker(...) method in SocketCluster (master) API for details on how
to send a message to a worker from the master process (and how to handle the response from the worker).
|
Methods:
| constructor([options]) |
Create the worker instance. You can pass an optional options object.
Since SocketCluster v14.2.0, the options object can be used to override properties from the main options object which was passed to the SocketCluster master instance.
You can also use the options object to pass a custom authEngine and codecEngine to the SCWorker instance.
|
||
| getSCServer() | Returns the SCServer instance associated with this worker. Note that you no longer have to use this method; you can now simply access the worker.scServer property directly instead. | ||
| getHTTPServer() | Returns the Node.js HTTP server associated with this worker. Note that this server's 'request' event will not trigger for requests which are handled internally by SocketCluster. If you would like to handle all requests (including ones for URLs reserved by SC), you will need to listen for the 'rawRequest' event. This is not recommended though unless you know what you're doing. Note that you no longer have to use this method; you can now simply access the worker.httpServer property directly instead. | ||
| setAuthEngine(authEngine) [Deprecated] |
This feature is deprecated, the recommended approach is to pass the authEngine as a property of the options object when constructing the SCWorker instance.
Set a custom auth engine for use throughout SC. This new engine will be used internally to create/sign and verify auth tokens.
The provided auth engine will become accessible from the 'worker.auth' property inside your workerController (worker.js).
The provided authEngine needs to provide a 'verifyToken' and a 'signToken' method - See the
default engine for details.
|
||
| sendToMaster(data, [callback]) |
Send some data to the master process from this worker. You will be able to handle this data from inside the master process by listening for the
'workerMessage' event. See here for more details.
Since SocketCluster v6.6.0, you can provide an optional callback as the second argument; it should be in the
form function (err, data) { /* ... */ } - Note that the master will need to respond
to the 'workerMessage' event by invoking a respond function; this is a convenient way to collect data back from the master process in response to this event.
If the master does not invoke the respond function, then this callback will receive an instance of TimeoutError as the first argument.
The timeout is defined by the ipcAckTimeout option - See the SocketCluster (server) API for details.
|
||
| getSocketPath() | Returns the URL path used by real-time socket connections. The method name getSocketURL() has been deprecated. | ||
| getStatus() | Returns an object containing statistics about the current worker including number of connected clients and also number of HTTP and real-time requests per minute. | ||
| addMiddleware(type, middlewareFn) |
Lets you add middleware functions which can be used to control the worker bootstrap process.
|