From 4a19854eb92c2127fa2ce51b1452bd997084015c Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Thu, 28 May 2026 14:34:19 -0400 Subject: [PATCH] docs: per-client High-level walker example using LazyBrowseNode Add a "High-level walker" subsection under each client's "Browsing lazily" section showing idiomatic use of LazyBrowseNode (browse + expand, idempotency note, redeploy refresh pattern). --- clients/dotnet/README.md | 26 ++++++++++++++++++++++++++ clients/go/README.md | 40 ++++++++++++++++++++++++++++++++++++++++ clients/java/README.md | 30 ++++++++++++++++++++++++++++++ clients/python/README.md | 24 ++++++++++++++++++++++++ clients/rust/README.md | 25 +++++++++++++++++++++++++ 5 files changed, 145 insertions(+) diff --git a/clients/dotnet/README.md b/clients/dotnet/README.md index 55e8911..eca5e15 100644 --- a/clients/dotnet/README.md +++ b/clients/dotnet/README.md @@ -218,6 +218,32 @@ for (int i = 0; i < roots.Children.Count; i++) } ``` +#### High-level walker + +For UI trees, the client provides a `LazyBrowseNode` walker that handles +sibling pagination and the `child_has_children` hint for you: + +```csharp +await using GalaxyRepositoryClient repository = GalaxyRepositoryClient.Create( + new MxGatewayClientOptions { Endpoint = new Uri("http://localhost:5000"), ApiKey = apiKey }); +IReadOnlyList roots = await repository.BrowseAsync(); +foreach (LazyBrowseNode root in roots) +{ + if (root.HasChildrenHint) + { + await root.ExpandAsync(); + } + foreach (LazyBrowseNode child in root.Children) + { + Console.WriteLine($"{child.Object.TagName} ({(child.HasChildrenHint ? "has children" : "leaf")})"); + } +} +``` + +`ExpandAsync` is idempotent — calling it twice fires only one RPC, +and is safe under concurrent callers. To refresh after a Galaxy redeploy, call +`BrowseAsync` again from the root. + ### Watching deploy events `WatchDeployEventsAsync` opens the `WatchDeployEvents` server-streaming RPC. The diff --git a/clients/go/README.md b/clients/go/README.md index ecc6df7..069a331 100644 --- a/clients/go/README.md +++ b/clients/go/README.md @@ -143,6 +143,46 @@ for i, child := range reply.GetChildren() { } ``` +#### High-level walker + +For UI trees, the client provides a `LazyBrowseNode` walker that handles +sibling pagination and the `child_has_children` hint for you: + +```go +galaxy, err := mxgateway.DialGalaxy(ctx, mxgateway.Options{ + Endpoint: "localhost:5000", + APIKey: os.Getenv("MXGATEWAY_API_KEY"), + Plaintext: true, +}) +if err != nil { + log.Fatal(err) +} +defer galaxy.Close() + +roots, err := galaxy.Browse(ctx, nil) +if err != nil { + log.Fatal(err) +} +for _, root := range roots { + if root.HasChildrenHint() { + if err := root.Expand(ctx); err != nil { + log.Fatal(err) + } + } + for _, child := range root.Children() { + kind := "leaf" + if child.HasChildrenHint() { + kind = "has children" + } + fmt.Printf("%s (%s)\n", child.Object().GetTagName(), kind) + } +} +``` + +`Expand` is idempotent — calling it twice fires only one RPC, +and is safe under concurrent callers. To refresh after a Galaxy redeploy, call +`Browse` again from the root. + ### Watching deploy events `WatchDeployEvents` opens a server-streaming subscription. The server emits a diff --git a/clients/java/README.md b/clients/java/README.md index 8adb867..7417d12 100644 --- a/clients/java/README.md +++ b/clients/java/README.md @@ -139,6 +139,36 @@ for (int i = 0; i < children.size(); i++) { } ``` +#### High-level walker + +For UI trees, the client provides a `LazyBrowseNode` walker that handles +sibling pagination and the `child_has_children` hint for you: + +```java +MxGatewayClientOptions options = MxGatewayClientOptions.builder() + .endpoint("localhost:5000") + .apiKey(System.getenv("MXGATEWAY_API_KEY")) + .plaintext(true) + .build(); + +try (GalaxyRepositoryClient galaxy = GalaxyRepositoryClient.connect(options)) { + List roots = galaxy.browse(); + for (LazyBrowseNode root : roots) { + if (root.hasChildrenHint()) { + root.expand(); + } + for (LazyBrowseNode child : root.getChildren()) { + String kind = child.hasChildrenHint() ? "has children" : "leaf"; + System.out.println(child.getObject().getTagName() + " (" + kind + ")"); + } + } +} +``` + +`expand` is idempotent — calling it twice fires only one RPC, +and is safe under concurrent callers. To refresh after a Galaxy redeploy, call +`browse` again from the root. + ### Watching deploy events `GalaxyRepository.WatchDeployEvents` is a server-streaming RPC: the gateway diff --git a/clients/python/README.md b/clients/python/README.md index d126bc2..5021db0 100644 --- a/clients/python/README.md +++ b/clients/python/README.md @@ -157,6 +157,30 @@ for child, has_children in zip(reply.children, reply.child_has_children): print(child.tag_name, "expand=" + str(has_children)) ``` +#### High-level walker + +For UI trees, the client provides a `LazyBrowseNode` walker that handles +sibling pagination and the `child_has_children` hint for you: + +```python +async with await GalaxyRepositoryClient.connect( + endpoint="localhost:5000", + api_key="", + plaintext=True, +) as galaxy: + roots = await galaxy.browse() + for root in roots: + if root.has_children_hint: + await root.expand() + for child in root.children: + kind = "has children" if child.has_children_hint else "leaf" + print(f"{child.object.tag_name} ({kind})") +``` + +`expand` is idempotent — calling it twice fires only one RPC, +and is safe under concurrent callers. To refresh after a Galaxy redeploy, call +`browse` again from the root. + ### Watching deploy events `GalaxyRepositoryClient.watch_deploy_events` opens a server-streaming diff --git a/clients/rust/README.md b/clients/rust/README.md index 8eca189..ea9cdec 100644 --- a/clients/rust/README.md +++ b/clients/rust/README.md @@ -157,6 +157,31 @@ for (child, has_children) in reply.children.iter().zip(reply.child_has_children. } ``` +#### High-level walker + +For UI trees, the client provides a `LazyBrowseNode` walker that handles +sibling pagination and the `child_has_children` hint for you: + +```rust +let mut client = GalaxyClient::connect( + ClientOptions::new("http://localhost:5000").with_api_key(ApiKey::new(api_key)), +).await?; +let roots = client.browse(None).await?; +for root in &roots { + if root.has_children_hint() { + root.expand().await?; + } + for child in root.children().await { + let kind = if child.has_children_hint() { "has children" } else { "leaf" }; + println!("{} ({kind})", child.object().tag_name); + } +} +``` + +`expand` is idempotent — calling it twice fires only one RPC, +and is safe under concurrent callers. To refresh after a Galaxy redeploy, call +`browse` again from the root. + ### Watching deploy events `watch_deploy_events` opens the `WatchDeployEvents` server stream. The