Custom Hooks

[deontologician]

I've been looking at adding custom hooks for a while, so custom behaviors can be handled by consumers of rest_navigator without needing to subclass etc. HALNavigator isn't designed especially well for being extended by subclasses, and I don't like subclassing by external consumers anyway, it requires too much knowledge of the guts of the class.

Another principle is to make the hook system simple/limited at first, it can always get more capabilities later, and if someone really really needs an out, you can always subclass.

N = HALNavigator('https://example.com/api')
N.hook(rel='xx:hams').state = change_state_callback
N.hook(profile='some_profile').links = change_links_callback
N.hook(rel='xx:hams', name='barry').headers = change_session_headers_callback
N.hook(state=lambda s: s['foo']['bar'] == 12).state = change_state_callback
N.hook(header=('content-type', 'application/hal+json')).state = 

There will need to be a new class, with a few properties:

Hook
  state
  links
  headers
  side_effect

The Hook is created and registered by the .hook method on Navigators That method also returns the new Hook object.

my_hook = N.hook(...)
my_hook.side_effect = ...
my_hook.state = ...
... # sometime later
my_hook.unregister() # removes it from the navigator
# or alternately:
N.unregister_hook(my_hook)

The properties of the Hook class are:

• state - a function called with the current state, which returns a new state. That state will be set on the new Navigator
• links - receives the links from the new Navigator, and returns a new set of links to replace it. This might allow adding "pseudo resources" etc for convenience
• headers - receives the current session headers and returns a new dictionary of headers to use instead.
• side_effect - a function that receives the new Navigator and performs a side-effect. Its return value is ignored.

The hook method on HALNavigator has several keyword arguments (they can't be passed positionally):

def hook(self, **kwargs):

For each of these, the argument can either take a literal value to match, or it can take a function. The function receives the corresponding property and should return True or False to determine if the property matches

• rel matches the link relation of a new navigator
• state matches a navigator state (this will almost always be passed a function, since it's unlikely the entire state will want to be matched)
• profile receives the profile of a link.
• header is different in that it may receive a 2-tuple, either value of which may be a literal or a function. The first value matches the header name, the second matches the header value.
• Any other keyword will be assumed to be a property of the link from which the Navigator was created. So custom link properties like method could be done with:

N.hook(method='GET')

Other notes:

• When N.hook is called, it not only returns the Hook object, but it also registers the hook in a list on the Navigator called ._hooks.
• ._hooks should be shared between all Navigators from the same root.
• .unregister_hooks should work

This is a rough draft, and basically has my thoughts all out of order. @dudycooly, I'd appreciate any comments you have

[deontologician]

@dudycooly I made you a collaborator on this repository, so if you feel like working on this over the next two weeks have at it. I'm going to have limited internet until the 14th, and will be working on #7 (embedded support) offline. If you end up working on hooks, just assign yourself and merge whatever you think is good enough into next. I can probably comment from time to time when I get internet access.

[dudycooly]

@deontologician Unable to work on this project for last two days. On Hook,
you already have a detailed proposal and looks great.
This will be handy for any Advance users. I had a very simple case in my
mind initially and have started working on it.
Once you are back, will go through in detail

On 4 November 2014 01:21, Josh Kuhn notifications@github.com wrote:

@dudycooly https://github.com/dudycooly I made you a collaborator on
this repository, so if you feel like working on this over the next two
weeks have at it. I'm going to have limited internet until the 14th, and
will be working on #7
#7 (embedded
support) offline. If you end up working on hooks, just assign yourself and
merge whatever you think is good enough into next. I can probably comment
from time to time when I get internet access.

—
Reply to this email directly or view it on GitHub
#13 (comment)
.

[dudycooly]

@deontologician I am just wondering when you are planning to merge "next"
branch to master?
CREATE response fix went in master today may be over-written by this merge.
just heads up

On 6 November 2014 00:09, Jp jay.naveen@gmail.com wrote:

@deontologician Unable to work on this project for last two days. On
Hook, you already have a detailed proposal and looks great.
This will be handy for any Advance users. I had a very simple case in my
mind initially and have started working on it.
Once you are back, will go through in detail

On 4 November 2014 01:21, Josh Kuhn notifications@github.com wrote:

@dudycooly https://github.com/dudycooly I made you a collaborator on
this repository, so if you feel like working on this over the next two
weeks have at it. I'm going to have limited internet until the 14th, and
will be working on #7
#7 (embedded
support) offline. If you end up working on hooks, just assign yourself and
merge whatever you think is good enough into next. I can probably comment
from time to time when I get internet access.

—
Reply to this email directly or view it on GitHub
#13 (comment)
.

[deontologician]

Basically, I was going to merge next when it was ready for 0.3. I think
hooks and embedded support should get it there
On Nov 7, 2014 7:49 AM, "dudycooly" notifications@github.com wrote:

@deontologician I am just wondering when you are planning to merge "next"
branch to master?
CREATE response fix went in master today may be over-written by this
merge.
just heads up

On 6 November 2014 00:09, Jp jay.naveen@gmail.com wrote:

@deontologician Unable to work on this project for last two days. On
Hook, you already have a detailed proposal and looks great.
This will be handy for any Advance users. I had a very simple case in my
mind initially and have started working on it.
Once you are back, will go through in detail

On 4 November 2014 01:21, Josh Kuhn notifications@github.com wrote:

@dudycooly https://github.com/dudycooly I made you a collaborator on
this repository, so if you feel like working on this over the next two
weeks have at it. I'm going to have limited internet until the 14th,
and
will be working on #7
#7 (embedded
support) offline. If you end up working on hooks, just assign yourself
and
merge whatever you think is good enough into next. I can probably
comment
from time to time when I get internet access.

—
Reply to this email directly or view it on GitHub
<
https://github.com/deontologician/rest_navigator/issues/13#issuecomment-61579171>

.

—
Reply to this email directly or view it on GitHub
#13 (comment)
.

[deontologician]

@dudycooly I am finally back from vacation. Working on the embedded stuff still. Let me know if you want to discuss anything

[dudycooly]

@deontologician - Hope you had a good vacation. Let us catch up tonight

On 1 December 2014 at 02:07, Josh Kuhn notifications@github.com wrote:

@dudycooly https://github.com/dudycooly I am finally back from
vacation. Working on the embedded stuff still. Let me know if you want to
discuss anything

—
Reply to this email directly or view it on GitHub
#13 (comment)
.

[dudycooly]

@deontologician - Pls ping if you are online

[deontologician]

@dudycooly sorry I missed your message. I don't have your email, so just ping me when you get on if you can