Links, paths, and anchors #453
Conversation
| !!! info Action hashes aren't certain until zome function lifecycle completes | ||
| When you get an action hash back from the host function that creates it, it doesn't mean the action is available on the DHT yet, or will ever be available. The action isn't written until the function that writes it completes, then passes the action to validation. If the function or the validation fail, the action will be discarded. And if it is successful, the action won't become fully available on the DHT until it's been published to a sufficient number of peers. | ||
|
|
||
| It's safer to share action hashes with other peers or cells in a callback called `post_commit()`. If your coordinator zome defines this callback, it'll be called after every successful function call within that zome. |
There was a problem hiding this comment.
This warning confused me. What is the less-safe way to share hashes? Also, when and why would I be sharing the hashes?
Is this about sending signals to other peers so they get the updates quicker?
There was a problem hiding this comment.
Yeah this confused me too. In the context of linking to/from the action within the same zome call it was created there's no issue since all the actions will either be committed to the source chain or discarded atomically
| ); | ||
| ``` | ||
|
|
||
| A link is considered dead once its creation action has one or more delete-link actions associated with it. |
There was a problem hiding this comment.
I might also copy the same disclaimer from the entries page: "deleting" a link just creates another action marking the link as deleted and does not actually delete any data. And that a future potential purge feature will not apply to links as they are only actions.
|
|
||
| ### Define a link type | ||
|
|
||
| Every link has a type that you define in an integrity zome, just like [an entry](/build/entries/#define-an-entry-type). Links are simple enough that they have no entry content. Instead, their data is completely contained in the actions that write them. Here's what a link creation action contains, in addition to the [common action fields](/build/working-with-data/#entries-actions-and-records-primary-data): |
There was a problem hiding this comment.
The phrasing of sentences 2-4 is a bit confusing to me. I might just say explicitly: "a link is commited to the source chain as an action with no associated entry"
| ); | ||
| ``` | ||
|
|
||
| Links can't be updated; they can only be created or deleted. |
There was a problem hiding this comment.
Should we give some clarifying rationale for why they can't be updated?
There was a problem hiding this comment.
sure... if only I knew why 🤣
| ); | ||
| ``` | ||
|
|
||
| A link is considered dead once its creation action has one or more delete-link actions associated with it. |
There was a problem hiding this comment.
I'm not sure about using the term "dead" here -- in the web 2 context it usually means that a link's target is no longer hosted anywhere. I haven't seen the term used elsewhere in holochain, maybe we should just stick with "deleted"?
There was a problem hiding this comment.
I think I'll stick with 'dead' for now -- I get that it has a different meaning in Web2, but it's used in the codebase and all across the Core Concepts to describe entries whose creation actions have all been marked deleted, so it seems appropriate to use for links too. I also want some word to suggest that it hasn't been removed -- there's still a body lying around :)
| ); | ||
| ``` | ||
|
|
||
| To get all live _and dead_ links, along with any deletion actions, use [`hdk::prelude::get_link_details`](https://docs.rs/hdk/latest/hdk/link/fn.get_link_details.html). This function has the same options as `get_links` |
There was a problem hiding this comment.
same note as above about the terms "dead" and "live"
|
|
||
| ### Count links | ||
|
|
||
| If all you need is a count of matching links, such as for an unread messages badge, use [`hdk::prelude::count_links`](https://docs.rs/hdk/latest/hdk/prelude/fn.count_links.html). It has a different input with more options for querying (we'll likely update the inputs of `get_links` and `count_links` to match `count_links` in the future). |
There was a problem hiding this comment.
Might be worth noting some gotchas with count_links: it goes to the network first, so if you end up asking 2 different peers with differing dht syncs you may get 2 different answers (which may be odd behavior if your unread messages badge shows a smaller number than before without you reading any messages). You may also get a different count as the number returned from get_links for the same reason.
There was a problem hiding this comment.
Good point, although I feel like there's an entire story about that re: eventual consistency everywhere.
There was a problem hiding this comment.
Yeah it's more than just that though since it doesn't go to your cache so you may have more links than you receive via count
|
|
||
| While you can build this yourself, this is such a common pattern that the HDK implements it for you in the [`hdk::hash_path`](https://docs.rs/hdk/latest/hdk/hash_path/index.html) module. The implementation supports both anchors and **paths**, which are hierarchies of anchors. | ||
|
|
||
| !!! info Avoiding DHT hot spots |
There was a problem hiding this comment.
same note as above -- I think hot spots could be expanded on in its own section
| @@ -88,7 +96,7 @@ use movie_integrity::*; | |||
|
|
|||
| let movie = Movie { | |||
| title: "The Good, the Bad, and the Ugly", | |||
| director: "Sergio Leone" | |||
| director_hash: EntryHash::from_raw_36(vec![ /* hash of 'Sergio Leone' entry */ ]), | |||
There was a problem hiding this comment.
Wouldn't it be useful to also show how to get /* hash of 'Sergio Leone' entry */, or is this covered elsewhere in the guide?
There was a problem hiding this comment.
yup, there's a section on it elsewhere, although it's a bit long-winded. I might make it into its own article.
pdaoust
force-pushed
the
feat/guide/links
branch
2 times, most recently
from
d9ebbdb
to
6ae6740
Compare
pdaoust
force-pushed
the
feat/guide/links
branch
from
6ae6740
to
9792f1c
Compare
|
@mattyg I've done some reworking -- probably more than necessary -- so I'm requesting a re-review so we can get it published. Thanks! |
pdaoust
force-pushed
the
feat/guide/links
branch
from
699af44
to
f6d07d4
Compare
Resolves #467
Seeking review for: