[NOTIFICATION] Breaking changes to userspace code and airlock

18 views
Skip to first unread message

Liam Fitzgerald

unread,
Mar 26, 2021, 12:52:04 AMMar 26
to urbit-dev
Hi dev,
There are upcoming changes to interacting with the userspace agents
and push-hooks. I'll break down what those changes mean for
third-party developers.

# Breakdown of changes
Pokes to push-hooks (contact-update, metadata-update, graph-update,
group-update) have all changed to include a version number (e.g.
contact-update-0, metadata-update-0 etc.). These marks are
functionally identical to their unversioned counterparts, so no
changes to JSON (de)serialization or devasing are necessary. Facts
from stores will all have versioned marks.

# Airlock developers
You may continue to make unversioned pokes after the deploy, and they
will succeed, however unversioned poking is to be considered
deprecated and will be removed in the future.
If you wish to ensure compatibility between airlock and the
push-hooks, you may scry into the push-hook on /x/min-version to
receive the minimum supported version by that push hook.

# Gall agent developers

## If your agent pokes any of the landscape stores

Stores (with the exception of hark) only accept pokes of versioned
marks. Any references to the unversioned marks will have to be
replaced with the versioned marks. You may piggyback the hooks version
negotiation by poking the push-hook instead, but be aware that the
poke will be routed to the ship specified in the resource, which may
not be your local ship. Alternatively, you may use %poke-as to specify
a version, as long as the result of an /x/min-version scry into the
push-hook returns a version number less than or equal to the version
of the intended poke

## If your agent watches any of the landscape stores

Stores (with the exception of hark) will emit facts with a versioned
mark. Any references to the unversioned marks will have to be replaced
with the versioned marks. You may use %watch-as to specify a version
for the facts, as long as the /x/min-version scry is less than or
equal to the requested fact version.

## If your agent uses the hook libraries

For now, you will need to update your stores to use a mark version of
0, and declare `version` and `min-version ` to be 0 in the config of
the hooks. You will also need to ensure that the unversioned and
versioned marks are convertible to each other via +grab/+grow. Better
docs on leveraging the version negotiation will arrive soon.

Please let me know if you have any questions.
——
~hastuc-dibtux

https://urbit.org
Reply all
Reply to author
Forward
0 new messages