Hydra Methods

The following represents Hydra's publicly exported methods.

☕ As a module, Hydra is designed to hide and discourage use of its internal methods. This helps to ensure that Hydra behaves as intended across a growing list of services.

The list of methods below are organized by the sections which follow. Not all applications and services require the use of all of the methods listed.

• Setup - Module setup and service registration
• Discovery - Service discovery
• Presence - Presence inspection
• Health - Health check and logging
• Messaging - Message sending
• Routing - Message routing

Setup

init

Initialize Hydra with config object.

/**
 * @name init
 * @summary Initialize Hydra with config object.
 * @param {object} config - configuration object containing hydra specific keys/values
 * @return {object} promise - resolving if init success or rejecting otherwise
 */
init(config)

ready

Returns promise that resolves when initialization is complete.

/**
* @name ready
* @summary returns promise that resolves when initialization is complete
* @return {object} promise - resolving if init success or rejecting otherwise
*/
ready()

shutdown

Shutdown hydra safely.

/**
* @name _shutdown
* @summary Shutdown hydra safely.
*/
shutdown()

registerService

Registers this machine as a Hydra instance.

/**
 * @name registerService
 * @summary Registers this machine as a Hydra instance.
 * @description This is an optional call as this module might just be used to monitor and query instances.
 * @return {object} promise - resolving if registration success or rejecting otherwise
 */
registerService()

Discovery

getServiceName

Retrieves the service name of the current instance.

/**
 * @name getServiceName
 * @summary Retrieves the service name of the current instance.
 * @throws Throws an error if this machine isn't a instance.
 * @return {string} serviceName - returns the service name.
 */
getServiceName()

getServiceNodes

Retrieve a list of services even if inactive.

/**
 * @name getServiceNodes
 * @summary Retrieve a list of services even if inactive.
 * @return {promise} promise - returns a promise
 */

getServices

Retrieve a list of available instance services.

/**
 * @name getServices
 * @summary Retrieve a list of available instance services.
 * @return {promise} promise - returns a promise which resolves to an array of objects.
 */
getServices()

findService

Finds a service.

/**
 * @name findService
 * @summary Find a service.
 * @param {string} name - service name - note service name is case insensitive
 * @return {promise} promise - which resolves with service
 */
findService(name)

Presence

getServicePresence

Retrieve a service / instance's presence info.

/**
 * @name getServicePresence
 * @summary Retrieve a service / instance's presence info.
 * @param {string} name - service name - note service name is case insensitive
 * @return {promise} promise - which resolves with service presence
 */
getServicePresence(name)

hasServicePresence

/**
 * @name hasServicePresence
 * @summary Indicate if a service has presence.
 * @description Indicates if a service has presence, meaning the 
 *              service is running in at least one node.
 * @param {string} name - service name - note service name is case insensitive
 * @return {promise} promise - which resolves with TRUE if presence is found, FALSE otherwise
*/
hasServicePresence(name)

getInstanceID

Returns the instance id for this process.

/**
* @name getInstanceID
* @summary Return the instance id for this process
* @return {number} id - instanceID
*/
getInstanceID()

Health

sendToHealthLog

Log a message to the service's health log queue.

/**
 * @name sendToHealthLog
 * @summary Log a message to the service instance's health log queue.
 * @private
 * @throws Throws an error if this machine isn't a instance.
 * @param {string} type - type of message ('error', 'info', 'debug' or user defined)
 * @param {string} message - message to log
 */
sendToHealthLog(type, message)

getServiceHealthLog

Get this service's health log.

/**
 * @name getServiceHealthLog
 * @summary Get this service's health log.
 * @throws Throws an error if this machine isn't a instance
 * @param {string} name - name of instance, use getName() if current service is the target.
 *                        note service name is case insensitive.
 * @return {promise} promise - resolves to log entries
 */
getServiceHealthLog(name)

getHealth

Retrieves the service health info.

/**
 * @name getHealth
 * @summary Retrieve service health info.
 * @private
 * @return {object} obj - object containing service info
 */
getHealth()

getServiceHealthAll

Retrieves the health status of all instance services.

/**
 * @name getServiceHealthAll
 * @summary Retrieve the health status of all instance services.
 * @return {promise} promise - resolves with an array of objects containing instance health information.
 */
getServiceHealthAll()

Messaging

createUMFMessage

Create a UMF style message.

/**
 * @name createUMFMessage
 * @summary Create a UMF style message.
 * @description This is a helper function which helps format a UMF style message.
 *              The caller is responsible for ensuring that required fields such as
 *              "to", "from" and "body" are provided either before or after using
 *              this function.
 * @param {object} message - optional message overrides.
 * @return {object} message - a UMF formatted message.
 */
createUMFMessage(message)

makeAPIRequest

Makes an API request to a hydra service.

/**
 * @name makeAPIRequest
 * @summary Makes an API request to a hydra service.
 * @description If the service isn't present and the message object has its
 *              message.body.fallbackToQueue value set to true, then the
 *              message will be sent to the services message queue.
 * @param {object} message - UMF formatted message
 * @return {promise} promise - response from API in resolved promise or
 *                   error in rejected promise.
 */
makeAPIRequest(message)

sendMessage

Sends a message to all present instances of a hydra service.

/**
 * @name sendMessage
 * @summary Sends a message to all present instances of a  hydra service.
 * @param {string | object} message - Plain string or UMF formatted message object
 * @return {promise} promise - resolved promise if sent or
 *                   error in rejected promise.
 */
sendMessage(message)

sendReplyMessage

Sends a reply message based on the original message received.

/**
 * @name sendReplyMessage
 * @summary Sends a reply message based on the original message received.
 * @param {object} originalMessage - UMF formatted message object
 * @param {object} messageResponse - UMF formatted message object
 * @return {object} promise - resolved promise if sent or
 *                   error in rejected promise.
 */
sendReplyMessage(originalMessage, messageResponse)

Routing

registerRoutes

Registers routes.

/**
* @name registerRoutes
* @summary Register routes
* @note Routes must be formatted as UMF To routes. https://github.com/cjus/umf#%20To%20field%20(routing)
* @param {array} routes - array of routes
* @return {object} Promise - resolving or rejecting
*/
registerRoutes(routes)

getAllServiceRoutes

Retrieves all service routes.

/**
* @name getAllServiceRoutes
* @summary Retrieve all service routes.
* @return {object} Promise - resolving to an object with keys and arrays of routes
*/
getAllServiceRoutes()

matchRoute

Matches a route path to a list of registered routes

/**
* @name matchRoute
* @summary Matches a route path to a list of registered routes
* @private
* @param {string} routePath - a URL path to match
* @return {boolean} match - true if match, false if not
*/
matchRoute(routePath)

Message queues

queueMessage

Queues a message

/**
* @name queueMessage
* @summary Queue a message
* @param {object} message - UMF message to queue
* @return {promise} promise - resolving to the message that was queued or a rejection.
*/
queueMessage(message)

getQueuedMessage

Retrieves a queued message

/**
* @name getQueuedMessage
* @summary Retrieve a queued message
* @param {string} serviceName who's queue might provide a message
* @return {promise} promise - resolving to the message that was dequeued or a rejection.
*/
getQueuedMessage(serviceName)

markQueueMessage

Marks a queued message as either completed or not

/**
* @name markQueueMessage
* @summary Mark a queued message as either completed or not
* @param {object} message - message in question
* @param {boolean} completed - (true / false)
* @param {string} reason - if not completed this is the reason processing failed
* @return {promise} promise - resolving to the message that was dequeued or a rejection.
*/
markQueueMessage(message, completed, reason)