Provides semaphore-like functionality for multi-instance node applications that need to protect a critical section of code.
The npm should be installed on one server and all client instances as so:
npm install -g cloud-semaphore
const semaphore = require('cloud-semaphore');
semaphore.server(3202, ['some-api-key']);
const {
init,
waitOnSemaphore,
signalSemaphore
} = require('cloud-semaphore');
init('localhost', 3202, false, 'some-api-key' )
async function doSomethingImportant() {
const sem = await waitOnSemaphore('Name');
if(sem) {
/* perform critical section */
console.log('got it.');
await signalSemaphore(sem);
console.log('released it.');
}
}
doSomethingImportant();
As with traditional semaphores, care should be taken to minimize the time any one client holds the semaphore. Code that fails to release a semaphore will cause all other requests to block until the client process exits or its idle connections are closed. The server will notice that the connection holding the semaphore has closed and will then release it to the next waiter.
changeLogTargets(console);
changeLogTargets(console, callback);
console (boolean) (required)
Enabled log events will be sent to the console when 'console' is true.
callback (function(message))
This function will be called with a string describing log events when this function is
provided.
NA
disableLogEvent(component, eventType);
component (string) (required)
The component can be 'server' or 'client' depending on what service creates the eventType.
eventType (string) (required)
The server event type can be one of the following:
- info (defaults to true)
- alert (defaults to true)
- sem_events (defaults to false)
- sem_transition (defaults to false)
- debug (defaults to false)
The client event type can be one of the following:
- network_status (defaults to false)
- network_errors (defaults to true)
- usage_errors (defaults to false)
A JSON object describing the log event configuration after the requested event was disabled.
Null is returned when arguments are not recognized or when the server can not be reached.
enableLogEvent(component, eventType);
component (string) (required)
The component can be 'server' or 'client' depending on what service creates the eventType.
eventType (string) (required)
The server event type can be one of the following:
- info (defaults to true)
- alert (defaults to true)
- sem_events (defaults to false)
- sem_transition (defaults to false)
- debug (defaults to false)
The client event type can be one of the following:
- network_status (defaults to false)
- network_errors (defaults to true)
- usage_errors (defaults to false)
A JSON object describing the log event configuration after the requested event was enabled.
Null is returned when arguments are not recognized or when the server can not be reached.
This function is called once before any other APIs described here to instruct the library
how to contact the semaphore server.
init(semaphoreHost, semaphorePort)
init(semaphoreHost, semaphorePort, secure)
init(semaphoreHost, semaphorePort, secure, apiKey)
semaphoreHost (string)
The hostname where the semaphore server is listening.
semaphorePort (number)
The port where the semaphore server is listening.
secure (boolean)
Does the server support ssl. This service should never run on an unprotected
connection. API keys are passed in the headers and must be protected.
apiKey (string)
The string this instance will use to authenticate to the semaphore server.
Giving each client instance a unique key is helpful when debugging applications
that do not release the semaphore quickly and correctly.
NA
This function is valuable to see the current state of any semaphore and the
requests waiting for it.
observeSemaphore(name)
name (object) (required)
A name to identify the critical section of code the semaphore protects.
A JSON object is returned showing the current owner and waiters.
This function is used to start the semaphore server. The server is typically run
in its own process and by necessity in a single instance.
server(port, acceptedApiKeys)
server(port, acceptedApiKeys, sslCert, sslKey)
port (number) (required)
The TCP port where the server will listen.
acceptedApiKeys (array of strings) (required)
A list of keys the server will accept for authentication.
sslCert (string)
The server will require ssl connections when a certificate and key are provided
sslKey (string)
The server will require ssl connections when a certificate and key are provided
The returned object is an HTTP listener.
This function is used to release a currently held semaphore. When called, the next
consumer requesting the semaphore will be given it.
signalSemaphore(semaphore)
semaphore (object) (required)
The object returned by waitOnSemaphore must be passed as an argument to this
function.
The value 'true' will be returned when the semaphore is recognized and successfully
released.
This function creates connections to the server specified in the init function and
returns when the semaphore is owned exclusively by the caller.
waitOnSemaphore(name)
name (object) (required)
A name to identify the critical section of code the semaphore protects.
The returned value is an object describing the requested semaphore. The semaphore is
released by passing this object to signalSemaphore. If the semaphore server can not
be contacted for any reason, a null will be returned, a log event created and the
caller should not proceed.