09. Hooks

Hooks

Hooks allow to receive information when certain actions happen on Nexus. For example they allow to know when a task is pushed or pulled, when it timeouts or when it is resolved with a result or error.

The two types of hooks that are implemented give information about tasks and users.

How to subscribe to hooks

1. Subscribe to the hooks

Subscribe a pipe to one of the following topics:

• hook.*: All hooks
• hook.<type>.*: All hooks of a type
• hook.<type>|<prefix>: All hooks of a type on a prefix
• hook.<type>|<prefix>|<user>: All hooks of a type on a prefix from a user

type can be task or user.

prefix and user can be suffixed with .* to receive subprefixes hooks too.

2. Unban the hooks

When an action happens on nexus (a task is pushed, a user logins...) a hook is evaluated and only executed if it is unbanned. When starting Nexus, all hooks are banned.

To unban a hook, a publish to the topic hook.listen has to be done with the following data:

{
  "type": <type>,
  "path": <prefix>,
  "user": <user>
}

• If type is omitted, all hooks are unbanned.
• If type is present and path is omitted, all hooks of that type are unbanned.
• If type and path are present and user is omitted, all hooks of that type on that prefix are unbanned.
• If all fields are present only the specified hooks are unbanned.

When a hook is executed and nobody is subscribed to it, the hook is banned again. That's why it's important to subscribe to the hooks before unbanning them.

Task hooks

The data recived on the pipe is:

{
  "action": "pull|push|result|error|cancel|ttlExpired|timeout|reject|pusherDisconnect|pullerDisconnect",
  "id": <task_id>,
  ... other fields depending on the action (see hook() calls on the code)
}

User hooks

The data recived on the pipe is:

{
  "action": "login|create|delete|setTags|delTags|setPass|...",
  ... other fields depending on the action (see hook() calls on the code)
}

Example: using hook nxctl

In this example we will subscribe to all tasks on nayar.* prefixes.

Create pipe: terminal 1

$ nxctl -u root -p root pipe read
2016/10/05 13:13:46 Logged as root
2016/10/05 13:13:46 Pipe created: <pipe_id>

This pipe shows data from the subscribed hooks

Subscribe pipe to hooks: terminal 2

$ nxctl -u root -p root topic sub <pipe_id> "hook.task|nayar.*"
2016/10/05 13:13:49 Logged as root
2016/10/05 13:13:49 OK

Unban nayar. hooks:* terminal 2

$ nxctl -u root -p root topic pubj hook.listen '{"type":"task", "path":"nayar.*"}'
2016/10/05 13:13:49 Logged as root
2016/10/05 13:13:49 Result: map[ok:true sent:1]

Now the hook subscription is done and following task pushes, pulls and other actions will be received on the pipe.