Build guide: signals #534

pdaoust · 2025-02-18T18:51:49Z

Closes #471 . Covers both local and remote signals.

src/pages/build/signals.md

matthme · 2025-02-19T11:20:22Z

src/pages/build/signals.md

+    client.on("signal", (signal: Signal) => {
+        // There's currently only one useful signal type to listen for -- an
+        // app signal.
+        if (!(SignalType.App in signal)) return;


This is about to change in holochain 0.5 with the new enum serialization. Just as a heads up. It will be something like

if (signal.type !== "app") return;

matthme · 2025-02-19T11:21:46Z

src/pages/build/signals.md

+## Remote signals
+
+Agents can also send remote signals to each other using the [`send_remote_signal`](https://docs.rs/hdk/latest/hdk/p2p/fn.send_remote_signal.html) host function and a [`recv_remote_signal` callback](/build/callbacks-and-lifecycle-hooks/#define-a-recv-remote-signal-callback), which takes a single argument of any type and returns `ExternResult<()>`.
+


Maybe it would be worth writing here about the distinction from a remote call, i.e. that these remote signals are not waiting for a response whatsoever and have no guarantee of delivery.

Yes agree that should be documented but the same is actually true of local signals. No guarantees in either case. I've commented similarly above.

src/pages/build/signals.md

matthme · 2025-02-19T11:23:44Z

src/pages/build/signals.md

+pub fn recv_remote_signal(payload: RemoteSignal) -> ExternResult<()> {
+    if let RemoteSignal::Heartbeat = payload {
+        let caller = call_info()?.provenance;
+        emit_signal(LocalSignal::Heartbeat(caller))?;


Suggested change

emit_signal(LocalSignal::Heartbeat(caller))?;

// On the receiving end we forward the remote signal to the front-end by emitting a local signal

emit_signal(LocalSignal::Heartbeat(caller))?;

matthme · 2025-02-19T11:25:53Z

src/pages/build/signals.md

+```
+
+!!! info Remote signal handlers are just zome functions
+`send_remote_signal` is sugar for a [remote call](/build/calling-zome-functions/#call-a-zome-function-from-another-agent-in-the-network) to a zome function named  `recv_remote_signal` with no capability secret<!-- TODO: link to capabilities page -->. It works differently from a usual remote call, though, in that it's 'send-and-forget' --- it won't return an error if anything fails. In practice, these two are equivalent:


send_remote_signal is sugar for a remote call to a zome function named recv_remote_signal with no capability secret

Is this really correct? Because as written above, there is no timeout involved so I'm wondering whether there is actually a difference of how it's implemented under the hood but I'm not familiar with that part of the holochain code.

So I'm actually sceptical that they are equivalent in practice. Have you tried that out, including situations where peers to which a heartbeat is sent are offline?

hmmmm, I forgot that there's a timeout that gets ignored at the core/ribosome level. Good point.

Co-authored-by: matthme <[email protected]>

ThetaSinner · 2025-02-24T15:36:57Z

src/pages/build/signals.md

+
+### Emit a signal
+
+Your coordinator zome emits a signal with the [`emit_signal`](https://docs.rs/hdk/latest/hdk/p2p/fn.emit_signal.html) host function. You can call this function from a regular [zome function](/build/zome-functions/) or the [`init`](/build/callbacks-and-lifecycle-hooks/#define-an-init-callback), [`recv_remote_signal`](/build/callbacks-and-lifecycle-hooks/#define-a-recv-remote-signal-callback), or [`post_commit`](/build/callbacks-and-lifecycle-hooks/#define-a-post-commit-callback) callbacks.


Suggested change

Your coordinator zome emits a signal with the [`emit_signal`](https://docs.rs/hdk/latest/hdk/p2p/fn.emit_signal.html) host function. You can call this function from a regular [zome function](/build/zome-functions/) or the [`init`](/build/callbacks-and-lifecycle-hooks/#define-an-init-callback), [`recv_remote_signal`](/build/callbacks-and-lifecycle-hooks/#define-a-recv-remote-signal-callback), or [`post_commit`](/build/callbacks-and-lifecycle-hooks/#define-a-post-commit-callback) callbacks.

Your coordinator zome emits a signal with the [`emit_signal`](https://docs.rs/hdk/latest/hdk/p2p/fn.emit_signal.html) host function. It takes any serializable input and you can call this function from a regular [zome function](/build/zome-functions/) or the [`init`](/build/callbacks-and-lifecycle-hooks/#define-an-init-callback), [`recv_remote_signal`](/build/callbacks-and-lifecycle-hooks/#define-a-recv-remote-signal-callback), or [`post_commit`](/build/callbacks-and-lifecycle-hooks/#define-a-post-commit-callback) callbacks.

ThetaSinner

This is looking good. I have a few minor comments but mostly happy. I like how focused this one is on giving code examples and just enough description.

ThetaSinner · 2025-02-24T15:38:47Z

src/pages/build/signals.md

+
+### Listen for a signal
+
+The UI subscribes to signals with the [`AppWebsocket.prototype.on`](https://github.com/holochain/holochain-client-js/blob/main/docs/client.appwebsocket.on.md) method. The signal handler should expect signals from any coordinator zome in any cell in the agent's hApp instance, and can discriminate between them by cell ID and zome name.


I'd prefer to say something like "Signals are emitted on by Holochain on connected app websockets. A Holochain client will provide a way to receive these signals." Then, "For example, with the TypeScript client..."

Part of my reason for that, is something I can see is missing. If there are no connected app websockets then Holochain doesn't buffer messages. There's no guaranteed delivery, and no way for the app to know if anybody was listening. It's just a broadcast and anything that happens to receive it can act on the information.

I think this would be one of the gotchas that the ticket was asking for.

ThetaSinner · 2025-02-24T15:41:41Z

src/pages/build/signals.md

+import type { Signal, AppSignal, AgentPubKey } from "@holochain/client";
+import { SignalType, encodeHashToBase64 } from "@holochain/client";
+
+// Duplicate your zome's signal types in the UI.


Suggested change

// Duplicate your zome's signal types in the UI.

// Represent your zome's signal types in the UI.

Maybe? It's not really duplication, they can't share code really. People are also free to set up code generation if they want.

ThetaSinner · 2025-02-24T15:43:47Z

src/pages/build/signals.md

+        // There's currently only one useful signal type to listen for -- an
+        // app signal.


Maybe just leave this as "Signals coming from a coordinator are of the App type"? I don't think it's that accurate to say system signals aren't useful even though they're currently only used in countersigning. Then there's also the maintenance of comments like this as Holochain changes. The chances that we'll remember to update this is low.

ThetaSinner · 2025-02-24T15:45:08Z

src/pages/build/signals.md

+## Remote signals
+
+Agents can also send remote signals to each other using the [`send_remote_signal`](https://docs.rs/hdk/latest/hdk/p2p/fn.send_remote_signal.html) host function and a [`recv_remote_signal` callback](/build/callbacks-and-lifecycle-hooks/#define-a-recv-remote-signal-callback), which takes a single argument of any type and returns `ExternResult<()>`.
+


Yes agree that should be documented but the same is actually true of local signals. No guarantees in either case. I've commented similarly above.

ThetaSinner · 2025-02-24T15:53:27Z

src/pages/build/signals.md

+```
+
+!!! info Remote signal handlers are just zome functions
+`send_remote_signal` is sugar for a [remote call](/build/calling-zome-functions/#call-a-zome-function-from-another-agent-in-the-network) to a zome function named  `recv_remote_signal` with no capability secret<!-- TODO: link to capabilities page -->. It works differently from a usual remote call, though, in that it's 'send-and-forget' --- it doesn't block execution waiting for a response, and it doesn't return an error if anything fails. Other than that, the following two are roughly equivalent.


Suggested change

`send_remote_signal` is sugar for a [remote call](/build/calling-zome-functions/#call-a-zome-function-from-another-agent-in-the-network) to a zome function named `recv_remote_signal` with no capability secret. It works differently from a usual remote call, though, in that it's 'send-and-forget' --- it doesn't block execution waiting for a response, and it doesn't return an error if anything fails. Other than that, the following two are roughly equivalent.

`send_remote_signal` is sugar for a [remote call](/build/calling-zome-functions/#call-a-zome-function-from-another-agent-in-the-network) to a zome function named `recv_remote_signal`. This target function exists by convention and must be given an `Unrestricted` capability grant for this to work. . It works differently from a usual remote call, though, in that it's 'send-and-forget' --- it doesn't block execution waiting for a response, and it doesn't return an error if anything fails. Other than that, the following two are roughly equivalent.

ThetaSinner · 2025-02-24T15:54:10Z

src/pages/build/signals.md

+}
+```
+
+This means an agent needs to set up an [`Unrestricted` capability grant](https://docs.rs/holochain_integrity_types/latest/holochain_integrity_types/capability/enum.CapAccess.html#variant.Unrestricted)<!--TODO: link to capabilities page --> for it, so other agents can call it. Take care that this function does as little as possible, to avoid people abusing it. Permissions and privileges are another topic which we'll talk about soon.<!-- TODO: delete this sentence -->


Oh okay, we're saying something about this in two places, maybe we can unify?

ThetaSinner · 2025-02-24T17:21:31Z

src/pages/build/signals.md

+}
+
+#[hdk_extern]
+pub fn send_heartbeat(receivers: Vec<AgentPubKey>) -> ExternResult<()> {


If we're documenting with code like this, is it explicitly worth calling out that this forces Holochain to open and maintain connections for the heartbeat? So you wouldn't want logic that connects to everyone who is using your app. Holochain isn't designed to operate that many connections. It's fine like we do for syn with 2-10 people updating stickies, but in general you shouldn't be deliberately opening connections to every agent on the network.

Maybe that's out of scope or maybe that's a motivation to keep code samples even more minimal? This could just be a message getting sent, rather than a pattern

pdaoust added 6 commits February 13, 2025 13:27

feat: stub page for signals, added to navs

903ec2f

feat: signals page all fleshed out

9c9ef87

edit: move remote signal stuff from lifecycle hooks to signals page

17f3a11

edit: simplify signal code examples

0719f86

edit: fix bugs in signals code

66bb64b

chore: todo sweep for signals

821e377

pdaoust marked this pull request as ready for review February 18, 2025 22:08

pdaoust requested a review from a team February 18, 2025 22:09

pdaoust enabled auto-merge (squash) February 18, 2025 22:15

matthme reviewed Feb 19, 2025

View reviewed changes

pdaoust and others added 4 commits February 21, 2025 10:21

Apply suggestions from code review

ff44ed1

Co-authored-by: matthme <[email protected]>

edit: remove heartbeat-via-zome-call example

dccbca5

edit: send_remote_signal isn't exactly equivalent to call_zome

3f0af48

chore: note about SignalType changing in 0.5

ec26e49

ThetaSinner reviewed Feb 24, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Build guide: signals #534

Build guide: signals #534

pdaoust commented Feb 18, 2025

matthme Feb 19, 2025

matthme Feb 19, 2025

ThetaSinner Feb 24, 2025

matthme Feb 19, 2025

matthme Feb 19, 2025

matthme Feb 19, 2025

pdaoust Feb 19, 2025

ThetaSinner Feb 24, 2025

ThetaSinner left a comment

ThetaSinner Feb 24, 2025

ThetaSinner Feb 24, 2025

ThetaSinner Feb 24, 2025

ThetaSinner Feb 24, 2025

ThetaSinner Feb 24, 2025

ThetaSinner Feb 24, 2025

ThetaSinner Feb 24, 2025

ThetaSinner Feb 24, 2025

		## Remote signals

		Agents can also send remote signals to each other using the [`send_remote_signal`](https://docs.rs/hdk/latest/hdk/p2p/fn.send_remote_signal.html) host function and a [`recv_remote_signal` callback](/build/callbacks-and-lifecycle-hooks/#define-a-recv-remote-signal-callback), which takes a single argument of any type and returns `ExternResult<()>`.

	emit_signal(LocalSignal::Heartbeat(caller))?;
	// On the receiving end we forward the remote signal to the front-end by emitting a local signal
	emit_signal(LocalSignal::Heartbeat(caller))?;


		### Emit a signal

		Your coordinator zome emits a signal with the [`emit_signal`](https://docs.rs/hdk/latest/hdk/p2p/fn.emit_signal.html) host function. You can call this function from a regular [zome function](/build/zome-functions/) or the [`init`](/build/callbacks-and-lifecycle-hooks/#define-an-init-callback), [`recv_remote_signal`](/build/callbacks-and-lifecycle-hooks/#define-a-recv-remote-signal-callback), or [`post_commit`](/build/callbacks-and-lifecycle-hooks/#define-a-post-commit-callback) callbacks.


		### Listen for a signal

		The UI subscribes to signals with the [`AppWebsocket.prototype.on`](https://github.com/holochain/holochain-client-js/blob/main/docs/client.appwebsocket.on.md) method. The signal handler should expect signals from any coordinator zome in any cell in the agent's hApp instance, and can discriminate between them by cell ID and zome name.

	// Duplicate your zome's signal types in the UI.
	// Represent your zome's signal types in the UI.

		// There's currently only one useful signal type to listen for -- an
		// app signal.

Build guide: signals #534

Are you sure you want to change the base?

Build guide: signals #534

Conversation

pdaoust commented Feb 18, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ThetaSinner left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment