--- title: "Explorer source" url: "https://nsta1.github.io/Orleans.Lattice/samples/Explorer/source.html" source: "https://github.com/NSTA1/Orleans.Lattice/tree/release/9.9/samples/Explorer" documents: "Orleans.Lattice 9.9.0 (release line 9.9)" built: "2026-10-04" all-pages: "https://nsta1.github.io/Orleans.Lattice/llms.txt" --- # Explorer source Part of [Explorer sample](README.md). The source of the [Explorer](https://github.com/NSTA1/Orleans.Lattice/tree/release/9.9/samples/Explorer) sample. ## Program.cs ````csharp using System.Diagnostics; using Orleans.Lattice.Samples.Explorer; // Orleans.Lattice.Explorer sample: one process that shows every area of the // Explorer console with live data, with no cloud dependency. // // By default it runs a two-region estate: the east and west regions are two // single-silo Orleans clusters in this process, each serving every control // plane the Explorer has an area for on its own gRPC endpoint, replicating with // each other over loopback gRPC, and sharing one in-memory backup sink. East // also serves the console, which connects to east (or to west, with // --explorer-region west). Tenancy is on, with two seeded tenants. --minimal // keeps the single-region experience with no tenancy and no peer. // // The console signs in automatically as the bootstrap administrator, so every // administrator-gated area lights up. Telemetry is the one area that stays // hidden: it reads a Prometheus-compatible metrics backend, which this sample // does not run. README.md walks each area. if (!ExplorerSampleOptions.TryParse(args, Environment.GetEnvironmentVariable, out var options, out var error)) { Console.WriteLine(error); return 2; } var clock = Stopwatch.StartNew(); Console.WriteLine(options.Minimal ? "Starting one region..." : "Starting the east and west regions..."); await using var sample = ExplorerSample.Create(options); await sample.StartAsync(); SampleBanner.Write(Console.Out, sample, clock.Elapsed); sample.PeerLink.Changed += paused => Console.WriteLine(paused ? "Peer link PAUSED: replication between east and west is refused. Watch Replication go Lagging, then Stalled." : "Peer link RESUMED: the regions catch up."); using var stop = new CancellationTokenSource(); Console.CancelKeyPress += (_, e) => { e.Cancel = true; stop.Cancel(); }; if (sample.West is not null) { _ = Task.Run(() => ReadPeerToggles(sample.PeerLink, stop.Token)); } try { await Task.Delay(Timeout.Infinite, stop.Token); } catch (OperationCanceledException) { Console.WriteLine("Stopping..."); } return 0; // P (or a line starting with p, when input is redirected) pauses or resumes the // link between the regions. static void ReadPeerToggles(PeerLink link, CancellationToken stop) { while (!stop.IsCancellationRequested) { if (Console.IsInputRedirected) { var line = Console.In.ReadLine(); if (line is null) { return; } if (line.Trim().StartsWith('p') || line.Trim().StartsWith('P')) { link.Toggle(); } } else if (Console.ReadKey(intercept: true).Key == ConsoleKey.P) { link.Toggle(); } } } ```` ## Apps/TaskBoard/src/manifest.json ````json { "identity": { "slug": "task-board", "version": "1.0.0", "provenance": { "source": "in-image", "publisher": "Orleans.Lattice samples", "reference": "embedded:Orleans.Lattice.Samples.Explorer.TaskBoard.manifest.json" } }, "presentation": { "displayName": "Task board", "summary": "A three-column task board whose cards live as JSON values in the app's own tree.", "description": "Task board is the Explorer's pilot app with an untrusted UI.\nIt lists, adds, moves and deletes task cards stored under tasks/{id} in its one tree, and deep-links the selected card into the Explorer's address line.\nViewers can read the board. Editors can also change it.", "icon": { "path": "icon.svg", "digest": "c367e956895304c28f0936bd8f80db36308cfd837e8827c71ebe87940b4403a6" }, "categories": ["productivity", "sample"], "publisherDisplayName": "Orleans.Lattice samples" }, "trees": [{ "name": "tasks" }], "roles": [ { "name": "viewer", "operations": ["Read", "RangeRead"], "scopes": [{ "tree": "tasks" }] }, { "name": "editor", "operations": ["Read", "RangeRead", "Write", "Delete"], "scopes": [{ "tree": "tasks" }] } ], "replication": [{ "tree": "tasks", "mergeMode": "LwwRegister" }], "schema": [], "subscriptions": [], "mcpTools": [], "ui": { "entry": "index.html", "styles": ["app.css"], "scripts": [{ "path": "app.mjs", "module": true }], "assets": [ { "path": "index.html", "mediaType": "text/html", "digest": "48e16d67c058dd9f19f64f7b27bd03fc1dfb33d39d9774be88acd988df2b8bf2" }, { "path": "app.css", "mediaType": "text/css", "digest": "a2ad7151751a9261c28b05c7a7888bc3e6033eee044666d923a750fe22e2873b" }, { "path": "app.mjs", "mediaType": "text/javascript", "digest": "935cc197b6148e8d984e9d7adafccbf7ced3a6f45984487bbdd04b44f867775f" }, { "path": "icon.svg", "mediaType": "image/svg+xml", "digest": "c367e956895304c28f0936bd8f80db36308cfd837e8827c71ebe87940b4403a6" } ], "bundleDigest": "753d0f676b30113bd014d54b8dc0508bed711a2c904ac13ba88a8a2a10555c36", "bridge": [ { "operation": "context.read" }, { "operation": "data.read", "trees": ["tasks"] }, { "operation": "data.write", "trees": ["tasks"] }, { "operation": "data.delete", "trees": ["tasks"] }, { "operation": "nav.sync" }, { "operation": "ui.notify" } ], "minProtocol": 1 } } ```` ## Apps/TaskBoard/src/TaskBoard.csproj ````xml net10.0 enable enable Orleans.Lattice.Samples.Explorer.TaskBoard Orleans.Lattice.Samples.Explorer.TaskBoard false ```` ## Apps/TaskBoard/src/TaskBoardApp.cs ````csharp using System.Reflection; namespace Orleans.Lattice.Samples.Explorer.TaskBoard; /// /// Where the task-board sample app lives in this assembly. A silo registers it with the in-image /// app source through the three-argument AddLatticeApp overload: /// siloBuilder.AddLatticeApp(TaskBoardApp.Slug, TaskBoardApp.Assembly, TaskBoardApp.ManifestResourceName). /// public static class TaskBoardApp { /// The app slug the manifest declares. public const string Slug = "task-board"; /// The manifest's embedded-resource name. public const string ManifestResourceName = "Orleans.Lattice.Samples.Explorer.TaskBoard.manifest.json"; /// /// The embedded-resource name prefix of the UI bundle assets; it is the in-image source's default /// for , so no explicit prefix need be passed. /// public const string AssetResourcePrefix = "Orleans.Lattice.Samples.Explorer.TaskBoard.ui."; /// The assembly that carries the manifest and the bundle. public static Assembly Assembly => typeof(TaskBoardApp).Assembly; } ```` ## Apps/TaskBoard/test/TaskBoard.Tests.csproj ````xml net10.0 enable enable false Orleans.Lattice.Samples.Explorer.TaskBoard.Tests Orleans.Lattice.Samples.Explorer.TaskBoard.Tests ```` ## Apps/TaskBoard/test/TaskBoardBundleTests.cs ````csharp using System.Text.RegularExpressions; namespace Orleans.Lattice.Samples.Explorer.TaskBoard.Tests; /// /// The bundle is plain HTML, CSS and one self-contained ES module that reaches the Explorer only /// through globalThis.lattice, needs no toolchain, and hides every write control until /// context.read reports a role that may write. /// [TestFixture] public sealed class TaskBoardBundleTests { private static readonly string[] TextFiles = [ "manifest.json", "ui/index.html", "ui/app.css", "ui/app.mjs", "ui/icon.svg", "ui/.gitattributes", ".gitattributes", ]; [Test] public void Every_file_is_plain_ascii_with_lf_line_endings() { Assert.Multiple(() => { foreach (var file in TextFiles) { var bytes = TaskBoardFiles.ReadBytes(file); Assert.That(bytes.All(b => b is 0x09 or 0x0a or (>= 0x20 and < 0x7f)), Is.True, file + " is ASCII without CR"); } }); } [Test] public void The_line_endings_are_pinned() { Assert.That(TaskBoardFiles.ReadText("ui/.gitattributes"), Does.Contain("* text eol=lf")); Assert.That(TaskBoardFiles.ReadText(".gitattributes"), Does.Contain("manifest.json text eol=lf")); } [TestCase(@"^\s*import\b", "a static import")] [TestCase(@"\bimport\s*\(", "a dynamic import")] [TestCase(@"^\s*export\b", "an export")] [TestCase(@"\bfetch\s*\(", "fetch")] [TestCase(@"\bXMLHttpRequest\b", "XHR")] [TestCase(@"\bWebSocket\b", "a WebSocket")] [TestCase(@"\bEventSource\b", "an EventSource")] [TestCase(@"\b(localStorage|sessionStorage|indexedDB)\b", "storage")] [TestCase(@"\bdocument\.cookie\b", "cookies")] [TestCase(@"\b(window\.)?parent\b|\btop\b\.|\bpostMessage\b", "the parent window")] [TestCase(@"\b(innerHTML|outerHTML|insertAdjacentHTML)\b|document\.write", "HTML injection")] [TestCase(@"\beval\s*\(|\bnew\s+Function\b", "code generation")] [TestCase(@"\bsetTimeout\s*\(\s*[""'`]", "string timers")] public void The_module_is_self_contained_and_uses_only_the_lattice_api(string pattern, string what) { var module = TaskBoardFiles.ReadText("ui/app.mjs"); Assert.That(Regex.IsMatch(module, pattern, RegexOptions.Multiline), Is.False, "app.mjs must not use " + what); } [Test] public void The_module_reaches_the_host_through_the_lattice_global() { var module = TaskBoardFiles.ReadText("ui/app.mjs"); Assert.Multiple(() => { Assert.That(module, Does.Contain("await lattice.ready")); Assert.That(module, Does.Contain("lattice.on(\"context.changed\"")); Assert.That(module, Does.Contain("lattice.on(\"nav.changed\"")); Assert.That(module, Does.Contain("lattice.on(\"lattice.revoked\"")); Assert.That(module, Does.Contain("lattice.assetUrl(\"icon.svg\")")); }); } [Test] public void The_stylesheet_needs_no_url_import_or_hover() { var css = TaskBoardFiles.ReadText("ui/app.css"); Assert.Multiple(() => { Assert.That(css, Does.Not.Contain("url("), "a blob: stylesheet has no base URL"); Assert.That(css, Does.Not.Contain("@import")); Assert.That(css, Does.Not.Contain(":hover"), "no hover-only affordance"); }); } [Test] public void Custom_controls_keep_the_kit_touch_target() { var css = TaskBoardFiles.ReadText("ui/app.css"); var card = Regex.Match(css, @"\.tb-card\s*\{(?[^}]*)\}").Groups["body"].Value; Assert.That(card, Does.Contain("min-height: var(--lt-app-control-height)")); } [Test] public void The_columns_reflow_to_one_at_a_phone_width_without_width_queries() { var css = TaskBoardFiles.ReadText("ui/app.css"); Assert.That(css, Does.Contain("repeat(auto-fit, minmax(min(100%, 15rem), 1fr))")); Assert.That(css, Does.Not.Contain("@media (min-width").And.Not.Contain("@media (max-width")); } [TestCase("tb-add")] [TestCase("tb-detail-actions")] public void Write_controls_start_hidden(string id) { var html = TaskBoardFiles.ReadText("ui/index.html"); Assert.That(Regex.IsMatch(html, "id=\"" + id + "\"[^>]*\\shidden\\b"), Is.True, id + " is hidden until context.read reports a writer role"); } [Test] public void The_entry_has_no_form_because_the_sandbox_blocks_submission() { Assert.That(TaskBoardFiles.ReadText("ui/index.html"), Does.Not.Contain(" { Assert.That(svg, Does.StartWith(" { var path = a.GetProperty("path").GetString()!; return new AppUiAsset { Path = path, MediaType = a.GetProperty("mediaType").GetString()!, Digest = Sha256(TaskBoardFiles.ReadAsset(path)), }; }) .ToArray(); } [Test] public void The_manifest_digests_match_the_bundle_files() { using var document = JsonDocument.Parse(TaskBoardFiles.ReadBytes("manifest.json")); var root = document.RootElement; var ui = root.GetProperty("ui"); var expected = ExpectedAssets(); var expectedBundle = AppUiBundle.ComputeBundleDigest(expected.ToArray()); var expectedIcon = expected.Single(a => a.Path == "icon.svg").Digest; var drift = new StringBuilder(); foreach (var (declared, asset) in ui.GetProperty("assets").EnumerateArray().Zip(expected)) { if (declared.GetProperty("digest").GetString() != asset.Digest) drift.AppendLine($" ui.assets[{asset.Path}].digest = \"{asset.Digest}\""); } if (ui.GetProperty("bundleDigest").GetString() != expectedBundle) drift.AppendLine($" ui.bundleDigest = \"{expectedBundle}\""); if (root.GetProperty("presentation").GetProperty("icon").GetProperty("digest").GetString() != expectedIcon) drift.AppendLine($" presentation.icon.digest = \"{expectedIcon}\""); Assert.That(drift.ToString(), Is.Empty, "manifest.json has drifted from the bundle files. Set:" + Environment.NewLine + drift); } [Test] public void The_manifest_lists_exactly_the_bundle_files() { var onDisk = Directory.EnumerateFiles(Path.Combine(TaskBoardFiles.SourceDirectory, "ui")) .Select(Path.GetFileName) .Where(name => name != ".gitattributes"); Assert.That(TaskBoardFiles.Manifest().Ui!.Assets.Select(a => a.Path), Is.EquivalentTo(onDisk)); Assert.That(TaskBoardFiles.Manifest().Ui!.Assets.Select(a => a.Path), Is.EqualTo(TaskBoardFiles.AssetPaths)); } [Test] public void The_bundle_digest_is_the_f1_digest_of_the_assets() { var ui = TaskBoardFiles.Manifest().Ui!; Assert.That(AppUiBundle.ComputeBundleDigest(ui.Assets), Is.EqualTo(ui.BundleDigest)); } [Test] public void The_icon_digest_is_its_asset_digest() { var manifest = TaskBoardFiles.Manifest(); Assert.That(manifest.Presentation!.Icon!.Digest, Is.EqualTo(manifest.Ui!.Assets.Single(a => a.Path == "icon.svg").Digest)); } [Test] public void Every_embedded_resource_is_the_file_on_disk() { Assert.Multiple(() => { Assert.That(TaskBoardFiles.ReadEmbedded(TaskBoardApp.ManifestResourceName), Is.EqualTo(TaskBoardFiles.ReadBytes("manifest.json")), "manifest.json"); foreach (var path in TaskBoardFiles.AssetPaths) { Assert.That(TaskBoardFiles.ReadEmbedded(TaskBoardApp.AssetResourcePrefix + path), Is.EqualTo(TaskBoardFiles.ReadAsset(path)), path); } }); } } ```` ## Apps/TaskBoard/test/TaskBoardFiles.cs ````csharp using System.Reflection; using Orleans.Lattice.Apps; namespace Orleans.Lattice.Samples.Explorer.TaskBoard.Tests; /// Reads the task board's manifest and bundle, from disk and from the embedded resources. internal static class TaskBoardFiles { /// The bundle assets the manifest lists, in manifest order. public static readonly string[] AssetPaths = ["index.html", "app.css", "app.mjs", "icon.svg"]; /// The app library's source directory, stamped into this assembly at build time. public static string SourceDirectory { get; } = typeof(TaskBoardFiles).Assembly .GetCustomAttributes() .Single(a => a.Key == "TaskBoardSourceDirectory").Value!; /// Reads the bytes of a file under the app's source directory. public static byte[] ReadBytes(string relative) => File.ReadAllBytes(Path.Combine(SourceDirectory, relative.Replace('/', Path.DirectorySeparatorChar))); /// Reads a file under the app's source directory as text. public static string ReadText(string relative) => File.ReadAllText(Path.Combine(SourceDirectory, relative.Replace('/', Path.DirectorySeparatorChar))); /// Reads a bundle asset's bytes from disk. public static byte[] ReadAsset(string path) => ReadBytes("ui/" + path); /// Reads an embedded resource of the app assembly. public static byte[] ReadEmbedded(string resourceName) { using var stream = TaskBoardApp.Assembly.GetManifestResourceStream(resourceName) ?? throw new AssertionException($"The app assembly has no embedded resource '{resourceName}'."); using var buffer = new MemoryStream(); stream.CopyTo(buffer); return buffer.ToArray(); } /// Parses the embedded manifest, failing with every diagnostic when it does not validate. public static AppManifest Manifest() { using var stream = new MemoryStream(ReadEmbedded(TaskBoardApp.ManifestResourceName)); var result = AppManifestParser.Parse(stream); Assert.That(result.Errors, Is.Empty, string.Join("; ", result.Errors.Select(e => e.Path + ": " + e.Message))); return result.Manifest!; } } ```` ## Apps/TaskBoard/test/TaskBoardInImageSourceTests.cs ````csharp using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Options; using Orleans.Lattice.Apps; using Orleans.Lattice.Apps.Sources; namespace Orleans.Lattice.Samples.Explorer.TaskBoard.Tests; /// /// The task board registers through the same AddLatticeApp line the Explorer sample uses, /// and the in-image source then enumerates, resolves and serves it. /// [TestFixture] public sealed class TaskBoardInImageSourceTests { private static InImageAppSource Source() { var services = new ServiceCollection(); services.AddLatticeApp(TaskBoardApp.Slug, TaskBoardApp.Assembly, TaskBoardApp.ManifestResourceName); using var provider = services.BuildServiceProvider(); return new InImageAppSource(provider.GetRequiredService>()); } [Test] public void The_default_asset_prefix_is_the_one_the_app_embeds_under() { var registration = new InImageAppRegistration(AppSlug.Parse(TaskBoardApp.Slug), TaskBoardApp.Assembly, TaskBoardApp.ManifestResourceName); Assert.That(registration.AssetResourcePrefix, Is.EqualTo(TaskBoardApp.AssetResourcePrefix)); } [Test] public async Task The_app_enumerates_from_the_in_image_source() { var source = Source(); var page = await source.ListAsync(AppSourceQuery.Default); Assert.Multiple(() => { Assert.That(source.Descriptor.Key, Is.EqualTo("in-image")); Assert.That(page.Entries, Has.Count.EqualTo(1)); var entry = page.Entries[0]; Assert.That(entry.Slug.Value, Is.EqualTo(TaskBoardApp.Slug)); Assert.That(entry.IsAvailable, Is.True, string.Join("; ", entry.Errors.Select(e => e.Path + ": " + e.Message))); Assert.That(entry.Versions, Is.EqualTo(new[] { AppVersion.Parse("1.0.0") })); Assert.That(entry.Provenance!.Source, Is.EqualTo(InImageAppSource.SourceKey)); Assert.That(entry.Manifest!.Presentation!.DisplayName, Is.EqualTo("Task board")); }); } [Test] public async Task The_app_resolves_from_the_composed_source_set() { var set = new AppSourceSet([Source()]); var result = await set.ResolveAsync(AppSlug.Parse(TaskBoardApp.Slug), sourceKey: InImageAppSource.SourceKey); Assert.That(result.IsResolved, Is.True, string.Join("; ", result.Errors.Select(e => e.Path + ": " + e.Message))); Assert.That(result.Manifest!.Ui, Is.Not.Null); } [Test] public async Task Every_bundle_asset_opens_verified_from_the_in_image_source() { var source = Source(); var manifest = TaskBoardFiles.Manifest(); foreach (var asset in manifest.Ui!.Assets) { var opened = await source.OpenAssetAsync(manifest.Identity.Slug, manifest.Identity.Version, asset.Path, asset.Digest); Assert.That(opened.IsOpened, Is.True, asset.Path + ": " + opened.Status); Assert.That(opened.MediaType, Is.EqualTo(asset.MediaType), asset.Path); Assert.That(opened.Content.ToArray(), Is.EqualTo(TaskBoardFiles.ReadAsset(asset.Path)), asset.Path); } } } ```` ## Apps/TaskBoard/test/TaskBoardManifestTests.cs ````csharp using System.Text.RegularExpressions; using Orleans.Lattice.Apps; using Orleans.Lattice.Auth; namespace Orleans.Lattice.Samples.Explorer.TaskBoard.Tests; /// The task board's manifest: one tree, two roles, a presentation and a UI that asks only for what it uses. [TestFixture] public sealed class TaskBoardManifestTests { [Test] public void The_manifest_validates() { using var stream = new MemoryStream(TaskBoardFiles.ReadEmbedded(TaskBoardApp.ManifestResourceName)); var result = AppManifestParser.Parse(stream); Assert.That(result.IsValid, Is.True, string.Join("; ", result.Errors.Select(e => e.Path + ": " + e.Message))); } [Test] public void The_identity_is_the_task_board_slug() { var identity = TaskBoardFiles.Manifest().Identity; Assert.That(identity.Slug.Value, Is.EqualTo(TaskBoardApp.Slug)); Assert.That(identity.Provenance.Source, Is.EqualTo(InImageAppSource.SourceKey)); } [Test] public void The_app_declares_one_tree_named_tasks() { Assert.That(TaskBoardFiles.Manifest().Trees.Select(t => t.Name), Is.EqualTo(new[] { "tasks" })); } [Test] public void The_viewer_reads_and_the_editor_reads_and_writes_only_its_own_tree() { var roles = TaskBoardFiles.Manifest().Roles.ToDictionary(r => r.Name); Assert.Multiple(() => { Assert.That(roles.Keys, Is.EquivalentTo(new[] { "viewer", "editor" })); Assert.That(roles["viewer"].Operations, Is.EqualTo(LatticeOperation.Read | LatticeOperation.RangeRead)); Assert.That(roles["editor"].Operations, Is.EqualTo(LatticeOperation.Read | LatticeOperation.RangeRead | LatticeOperation.Write | LatticeOperation.Delete)); foreach (var role in roles.Values) { Assert.That(role.Scopes, Has.Length.EqualTo(1), role.Name); Assert.That(role.Scopes[0].Tree, Is.EqualTo("tasks"), role.Name); Assert.That(role.Scopes[0].App, Is.Null, role.Name + " stays in the app's own namespace"); Assert.That(role.Scopes[0].Kind, Is.EqualTo(LatticeScopeKind.Tree), role.Name); } }); } [Test] public void The_presentation_has_a_name_summary_description_and_svg_icon() { var presentation = TaskBoardFiles.Manifest().Presentation!; Assert.Multiple(() => { Assert.That(presentation.DisplayName, Is.EqualTo("Task board")); Assert.That(presentation.Summary, Is.Not.Null.And.Not.Empty); Assert.That(presentation.Description, Is.Not.Null.And.Not.Empty); Assert.That(presentation.Icon!.Path, Is.EqualTo("icon.svg")); }); } [Test] public void The_ui_is_a_fragment_one_stylesheet_and_one_module() { var ui = TaskBoardFiles.Manifest().Ui!; Assert.Multiple(() => { Assert.That(ui.Entry, Is.EqualTo("index.html")); Assert.That(ui.Styles, Is.EqualTo(new[] { "app.css" })); Assert.That(ui.Scripts, Has.Length.EqualTo(1)); Assert.That(ui.Scripts![0].Path, Is.EqualTo("app.mjs")); Assert.That(ui.Scripts[0].Module, Is.True); Assert.That(ui.MinProtocol, Is.EqualTo(AppUiProtocol.Current)); }); } [Test] public void The_ui_requests_exactly_the_pilot_bridge_operations() { var bridge = TaskBoardFiles.Manifest().Ui!.Bridge!; Assert.That(bridge.Select(b => b.Operation), Is.EqualTo(new[] { AppUiBridgeOperations.ContextRead, AppUiBridgeOperations.DataRead, AppUiBridgeOperations.DataWrite, AppUiBridgeOperations.DataDelete, AppUiBridgeOperations.NavSync, AppUiBridgeOperations.UiNotify, })); Assert.That(bridge.Where(b => AppUiBridgeOperations.IsDataOperation(b.Operation)).Select(b => b.Trees), Is.All.EqualTo(new[] { "tasks" })); } [Test] public void The_writer_roles_in_the_module_are_the_manifest_roles_that_can_write() { var module = TaskBoardFiles.ReadText("ui/app.mjs"); var declared = Regex.Match(module, @"const WRITER_ROLES = \[(?[^\]]*)\];"); Assert.That(declared.Success, Is.True, "app.mjs declares WRITER_ROLES"); var inModule = Regex.Matches(declared.Groups["list"].Value, "\"(?[a-z][a-z0-9_-]*)\"").Select(m => m.Groups["name"].Value); var writers = TaskBoardFiles.Manifest().Roles .Where(r => r.Operations.HasFlag(LatticeOperation.Write) && r.Operations.HasFlag(LatticeOperation.Delete)) .Select(r => r.Name); Assert.That(inModule, Is.EquivalentTo(writers)); Assert.That(writers, Is.EquivalentTo(new[] { "editor" })); } [Test] public void The_board_decides_write_access_from_context_read_roles_not_a_probe() { var module = TaskBoardFiles.ReadText("ui/app.mjs"); Assert.Multiple(() => { Assert.That(module, Does.Contain("context.roles")); Assert.That(module, Does.Contain("Array.isArray(context.roles)"), "an absent roles member infers no role"); Assert.That(module, Does.Not.Contain("probe").IgnoreCase, "no write probe"); Assert.That(Regex.Matches(module, "request\\(\"data\\.delete\"").Count, Is.EqualTo(1), "the only delete is the user's own delete"); Assert.That(Regex.IsMatch(module, @"canEdit:\s*false"), Is.True, "the board starts read-only"); Assert.That(module, Does.Contain("code === \"denied\""), "a denied write drops to read-only"); }); } [Test] public void The_module_uses_every_operation_it_requests_and_no_other() { var bridge = TaskBoardFiles.Manifest().Ui!.Bridge!.Select(b => b.Operation).ToHashSet(); var module = TaskBoardFiles.ReadText("ui/app.mjs"); Assert.Multiple(() => { foreach (var operation in AppUiBridgeOperations.All) { var used = module.Contains("request(\"" + operation + "\"", StringComparison.Ordinal); Assert.That(used, Is.EqualTo(bridge.Contains(operation)), operation); } }); } [Test] public void The_entry_is_a_valid_fragment() { Assert.That(AppManifestValidator.ValidateUiEntryFragment(TaskBoardFiles.ReadAsset("index.html")), Is.Empty); } } ```` ## DemoBasicAuthenticator.cs ````csharp using System.Text; using Orleans.Lattice; using Orleans.Lattice.Membership; namespace Orleans.Lattice.Samples.Explorer; /// /// A minimal demo that trusts the /// username in the console's auto-applied Basic sign-in as the caller subject id. /// The Explorer web console signs in with /// authorization: Basic base64(username:password); the auth / schema gRPC /// bindings (configured with a Basic credential scheme) strip the scheme /// and hand this authenticator the base64 token, which it decodes to recover the /// username. That username is the caller subject, and the sample registers it as /// a bootstrap administrator so the Access and Schema admin areas light up. /// /// A real deployment resolves the subject from a validated JWT or Entra token /// (see the JWT / Entra authenticators shipped with the Membership package); this /// sample uses a trivial trusted-token authenticator so the whole flow runs on /// one silo with no identity provider and the password is never checked. /// internal sealed class DemoBasicAuthenticator : ILatticeCredentialAuthenticator { /// The credential scheme this authenticator claims. public const string Scheme = "Basic"; /// The issuer stamped on the resolved principal. public const string Issuer = "https://issuer.explorer.sample/"; /// public bool CanHandle(in LatticeCredential credential) => string.Equals(credential.Scheme, Scheme, StringComparison.OrdinalIgnoreCase); /// public ValueTask AuthenticateAsync( LatticeCredential credential, CancellationToken cancellationToken = default) { // The token is base64(username:password); the caller subject is the // username. A malformed token resolves to no principal (anonymous). string username; try { var decoded = Encoding.UTF8.GetString(Convert.FromBase64String(credential.Token)); var separator = decoded.IndexOf(':'); username = separator >= 0 ? decoded[..separator] : decoded; } catch (FormatException) { return new ValueTask((LatticePrincipal?)null); } return string.IsNullOrEmpty(username) ? new ValueTask((LatticePrincipal?)null) : new ValueTask(new LatticePrincipal(username, Issuer)); } } ```` ## Explorer.csproj ````xml Exe net10.0 enable enable Orleans.Lattice.Samples.Explorer Orleans.Lattice.Samples.Explorer false true ```` ## ExplorerSample.cs ````csharp namespace Orleans.Lattice.Samples.Explorer; /// /// The whole sample: the east region, which serves the Explorer console, and - /// unless it runs --minimal - the west region it replicates with, the /// backup sink they share, the switch that pauses the link between them and /// the background writer that keeps the link busy. /// internal sealed class ExplorerSample : IAsyncDisposable { private readonly List _seedLog = []; private readonly Lock _seedLogLock = new(); private ExplorerSample( ExplorerSampleOptions options, SampleRegion east, SampleRegion? west, SampleSharedBackupSink? sink, PeerLink peerLink, SampleConsolePlan console) { Options = options; East = east; West = west; Sink = sink; PeerLink = peerLink; Console = console; } /// The options the sample was built with. public ExplorerSampleOptions Options { get; } /// The primary region, which serves the Explorer console. public SampleRegion East { get; } /// The peer region, or when the sample runs --minimal. public SampleRegion? West { get; } /// The backup sink the two regions share, or when the sample runs --minimal. public SampleSharedBackupSink? Sink { get; } /// The switch that pauses replication between the regions. public PeerLink PeerLink { get; } /// Where the console is served and which region it connects to. public SampleConsolePlan Console { get; } /// The background writer, once started; when the sample runs --minimal. public ReplicationWriter? Writer { get; private set; } /// The region the console connects to. public SampleRegion ConsoleRegion => West is { } west && Options.ExplorerRegion == west.Id ? west : East; /// Every region, primary first. public IReadOnlyList Regions => West is null ? [East] : [East, West]; /// One line per item seeded, once has completed. public IReadOnlyList SeedLog { get { lock (_seedLogLock) { return [.. _seedLog]; } } } /// Builds the sample's regions; nothing starts until . /// How the sample runs. /// The sample. public static ExplorerSample Create(ExplorerSampleOptions options) { ArgumentNullException.ThrowIfNull(options); var ports = options.Ports; var peerLink = new PeerLink(); var eastEndpoint = new Uri($"http://localhost:{ports.EastGrpc}"); if (options.Minimal) { var console = new SampleConsolePlan(ports.EastWeb, eastEndpoint, options.ExplorerConfigPath, options.SignInAs); var single = SampleRegion.Build( new SampleRegionPlan(SampleIdentities.EastRegion, ports.EastGrpc, ports.EastSilo, ports.EastGateway, Peer: null, console), options, sink: null, peerLink); return new ExplorerSample(options, single, west: null, sink: null, peerLink, console); } var westEndpoint = new Uri($"http://localhost:{ports.WestGrpc}"); var estateConsole = new SampleConsolePlan( ports.EastWeb, options.ExplorerRegion == SampleIdentities.WestRegion ? westEndpoint : eastEndpoint, options.ExplorerConfigPath, options.SignInAs); var sink = new SampleSharedBackupSink(); var east = SampleRegion.Build( new SampleRegionPlan( SampleIdentities.EastRegion, ports.EastGrpc, ports.EastSilo, ports.EastGateway, new SampleRegionPeer(SampleIdentities.WestRegion, ports.WestGrpc), estateConsole), options, sink, peerLink); var west = SampleRegion.Build( new SampleRegionPlan( SampleIdentities.WestRegion, ports.WestGrpc, ports.WestSilo, ports.WestGateway, new SampleRegionPeer(SampleIdentities.EastRegion, ports.EastGrpc), Console: null), options, sink, peerLink); return new ExplorerSample(options, east, west, sink, peerLink, estateConsole); } /// /// Starts every region, seeds them and, on the estate, starts the background /// writer. The console's persisted configuration is cleared first, so it /// connects to the region this run was asked for. /// /// Cancels the start. public async Task StartAsync(CancellationToken cancellationToken = default) { if (File.Exists(Console.ConfigPath)) { File.Delete(Console.ConfigPath); } await Task.WhenAll(Regions.Select(region => region.StartAsync(cancellationToken))).ConfigureAwait(false); // Every region is seeded, and the demo tree enrolled and known to the // peer, before the primary writes the data replication then carries. var staticDirectory = Options.Entra is null; await Task.WhenAll(Regions.Select(region => SampleSeeder.SeedRegionAsync(region, staticDirectory, Log, cancellationToken))) .ConfigureAwait(false); if (West is { } peer) { await SampleSeeder.EnrolAsync(East, peer, Log, cancellationToken).ConfigureAwait(false); } await SampleSeeder.SeedPrimaryAsync(East, West, Log, cancellationToken).ConfigureAwait(false); if (West is { } west) { var grainsEast = East.Services.GetRequiredService(); var grainsWest = west.Services.GetRequiredService(); Writer = new ReplicationWriter( [ new ReplicationWriterTarget(East.Id, grainsEast.GetGrain(SampleIdentities.FactoryFloorTree), "machine-", SampleIdentities.MachineCount), new ReplicationWriterTarget(west.Id, grainsWest.GetGrain(SampleIdentities.FactoryFloorTree), "west-sensor-", 4), ], Options.WriterInterval); Writer.Start(); if (Options.StartPeerPaused) { // Paused only once the seeded data has reached the peer, so every // link has made contact: from there the links age into Lagging // and then Stalled, rather than reading as never contacted. var arrived = await WaitForSeedOnPeerAsync(west, SeedArrivalBudget, cancellationToken).ConfigureAwait(false); PeerLink.Pause(); Log(arrived ? $"[{East.Id}] Peer link paused once the seeded data reached '{west.Id}'." : $"[{East.Id}] Peer link paused; the seeded data had not reached '{west.Id}' within {SeedArrivalBudget.TotalSeconds:0}s."); } } } /// How long --peer-paused waits for the seeded data to reach the peer before pausing regardless. public static TimeSpan SeedArrivalBudget { get; } = TimeSpan.FromSeconds(20); /// /// Waits until the last seeded machine of the demo tree and the last seeded /// card of acme's task board have both replicated to , /// or elapses. /// /// The peer region. /// The longest wait. /// Cancels the wait. /// Whether the data arrived. public static async Task WaitForSeedOnPeerAsync(SampleRegion peer, TimeSpan budget, CancellationToken cancellationToken = default) { ArgumentNullException.ThrowIfNull(peer); var grains = peer.Services.GetRequiredService(); var expected = new (ILattice Tree, string Key)[] { (grains.GetGrain(SampleIdentities.FactoryFloorTree), SampleSeeder.MachineKey(SampleIdentities.MachineCount - 1)), (grains.GetGrain(SampleSeeder.TaskBoardTree(SampleIdentities.AcmeTenant)), SampleSeeder.TaskKey(SampleSeeder.AcmeTasks[^1].Id)), }; using var budgetSource = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); budgetSource.CancelAfter(budget); using var poll = new PeriodicTimer(TimeSpan.FromMilliseconds(200)); try { do { using (LatticeSystemOrigin.Enter()) { var arrived = true; foreach (var (tree, key) in expected) { arrived &= await tree.GetAsync(key, budgetSource.Token).ConfigureAwait(false) is not null; } if (arrived) { return true; } } } while (await poll.WaitForNextTickAsync(budgetSource.Token).ConfigureAwait(false)); } catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested) { // The budget elapsed. } return false; } /// public async ValueTask DisposeAsync() { if (Writer is not null) { await Writer.DisposeAsync().ConfigureAwait(false); } foreach (var region in Regions) { await region.DisposeAsync().ConfigureAwait(false); } } private void Log(string line) { lock (_seedLogLock) { _seedLog.Add(line); } } } ```` ## ExplorerSampleOptions.cs ````csharp using System.Diagnostics.CodeAnalysis; using Orleans.Lattice.Membership; namespace Orleans.Lattice.Samples.Explorer; /// /// How the sample runs: the full two-region estate with tenancy (the default), /// or --minimal for the single-cluster experience; which region the /// Explorer connects to; and the identity-directory and group-merge settings /// read from the environment. /// internal sealed class ExplorerSampleOptions { /// The switch that keeps the single-cluster experience. public const string MinimalSwitch = "--minimal"; /// The switch that picks the region the Explorer connects to; it takes east or west. public const string ExplorerRegionSwitch = "--explorer-region"; /// The switch that pauses the link to the peer region as soon as the seeded data has reached it. public const string PeerPausedSwitch = "--peer-paused"; /// The switch that picks the identity the console signs in as automatically, or none. public const string SignInAsSwitch = "--sign-in-as"; /// The value that turns the automatic sign-in off. public const string NoSignIn = "none"; /// The switch that shifts every port by a number, for when the default ports are taken. public const string PortOffsetSwitch = "--port-offset"; /// The largest accepted, which keeps every port below 65536. public const int MaxPortOffset = 30000; /// The Entra tenant variable; set it with the other two to use the Entra identity directory. public const string EntraTenantIdVariable = "LATTICE_ENTRA_TENANT_ID"; /// The Entra client-id variable. public const string EntraClientIdVariable = "LATTICE_ENTRA_CLIENT_ID"; /// The Entra client-secret variable. public const string EntraClientSecretVariable = "LATTICE_ENTRA_CLIENT_SECRET"; /// The group-merge mode variable: Union (default), TokenOnly or DirectoryOnly. public const string MergeModeVariable = "LATTICE_MEMBERSHIP_MERGE_MODE"; /// The usage line printed with a rejected argument. public const string Usage = "Usage: dotnet run [-- [--minimal] [--explorer-region east|west] [--sign-in-as |none] [--peer-paused] [--port-offset ]]"; /// Whether to run one single-region cluster without tenancy, as the sample did before the estate. public bool Minimal { get; init; } /// The region the Explorer console connects to. public string ExplorerRegion { get; init; } = SampleIdentities.EastRegion; /// /// The identity the console signs in as automatically, or /// to leave it signed out so the sign-in dialog picks the identity. Signing out /// does not stick while an automatic sign-in is set: the console signs straight /// back in. /// public string? SignInAs { get; init; } = SampleIdentities.Administrator; /// Whether to pause the link to the peer region once the seeded data has reached it. public bool StartPeerPaused { get; init; } /// The Entra registration backing the identity directory, or for the static roster. public SampleEntraDirectory? Entra { get; init; } /// Whether locally-defined membership contributes to authorization. public SubjectGroupMergeMode GroupMergeMode { get; init; } = SubjectGroupMergeMode.Union; /// The ports the sample binds. public SamplePorts Ports { get; init; } = SamplePorts.Default; /// /// The Explorer console's persisted configuration file. The sample deletes it /// on start, so every run connects to the region it was asked for. /// public string ExplorerConfigPath { get; init; } = Path.Combine(AppContext.BaseDirectory, "explorer-sample-config.json"); /// How often the background writer updates one replicated key. public TimeSpan WriterInterval { get; init; } = TimeSpan.FromSeconds(1); /// /// Reads the command line and the environment, rejecting anything it does not /// recognise so a typo never silently runs a different sample. /// /// The command-line arguments. /// Reads an environment variable, returning when it is unset. /// The options, when the input is valid. /// Why the input was rejected, when it is not. /// Whether the input was valid. public static bool TryParse( IReadOnlyList args, Func environment, [NotNullWhen(true)] out ExplorerSampleOptions? options, [NotNullWhen(false)] out string? error) { ArgumentNullException.ThrowIfNull(args); ArgumentNullException.ThrowIfNull(environment); options = null; var minimal = false; var peerPaused = false; var portOffset = 0; string? region = null; var signInAs = SampleIdentities.Administrator; for (var i = 0; i < args.Count; i++) { var arg = args[i]; if (string.Equals(arg, MinimalSwitch, StringComparison.OrdinalIgnoreCase)) { minimal = true; } else if (string.Equals(arg, PeerPausedSwitch, StringComparison.OrdinalIgnoreCase)) { peerPaused = true; } else if (string.Equals(arg, ExplorerRegionSwitch, StringComparison.OrdinalIgnoreCase)) { if (i + 1 >= args.Count) { error = $"{ExplorerRegionSwitch} needs a region: {SampleIdentities.EastRegion} or {SampleIdentities.WestRegion}."; return false; } region = args[++i].Trim().ToLowerInvariant(); if (region is not (SampleIdentities.EastRegion or SampleIdentities.WestRegion)) { error = $"{ExplorerRegionSwitch} '{args[i]}' is not a region: use {SampleIdentities.EastRegion} or {SampleIdentities.WestRegion}."; return false; } } else if (string.Equals(arg, SignInAsSwitch, StringComparison.OrdinalIgnoreCase)) { var value = i + 1 < args.Count ? args[++i].Trim() : string.Empty; if (value.Length == 0 || value.StartsWith('-') || value.Contains(':', StringComparison.Ordinal) || value.Any(char.IsWhiteSpace)) { error = $"{SignInAsSwitch} needs a user name, such as {SampleIdentities.AcmeAdmin}, or {NoSignIn}."; return false; } signInAs = value; } else if (string.Equals(arg, PortOffsetSwitch, StringComparison.OrdinalIgnoreCase)) { if (i + 1 >= args.Count || !int.TryParse(args[++i], System.Globalization.NumberStyles.None, System.Globalization.CultureInfo.InvariantCulture, out portOffset) || portOffset > MaxPortOffset) { error = $"{PortOffsetSwitch} needs a whole number from 0 to {MaxPortOffset}."; return false; } } else { error = $"'{arg}' is not recognised. {Usage}"; return false; } } if (minimal && (peerPaused || region == SampleIdentities.WestRegion)) { error = $"{MinimalSwitch} runs one region with no peer, so it cannot be combined with {PeerPausedSwitch} or {ExplorerRegionSwitch} {SampleIdentities.WestRegion}."; return false; } if (!TryReadEntra(environment, out var entra, out var entraError)) { error = entraError; return false; } var mergeModeVariable = environment(MergeModeVariable); var mergeMode = SubjectGroupMergeMode.Union; if (!string.IsNullOrWhiteSpace(mergeModeVariable) && (!Enum.TryParse(mergeModeVariable, ignoreCase: true, out mergeMode) || !Enum.IsDefined(mergeMode))) { error = $"{MergeModeVariable} '{mergeModeVariable}' is not recognised. Set it to Union, TokenOnly or DirectoryOnly, or unset it to use Union."; return false; } options = new ExplorerSampleOptions { Minimal = minimal, ExplorerRegion = region ?? SampleIdentities.EastRegion, SignInAs = string.Equals(signInAs, NoSignIn, StringComparison.OrdinalIgnoreCase) ? null : signInAs, StartPeerPaused = peerPaused, Entra = entra, GroupMergeMode = mergeMode, Ports = SamplePorts.Default.Offset(portOffset), }; error = null; return true; } // Half-configuring Entra is rejected, so a partial configuration never // silently degrades to the static directory. private static bool TryReadEntra( Func environment, out SampleEntraDirectory? entra, [NotNullWhen(false)] out string? error) { var tenantId = environment(EntraTenantIdVariable); var clientId = environment(EntraClientIdVariable); var clientSecret = environment(EntraClientSecretVariable); var set = (string.IsNullOrWhiteSpace(tenantId) ? 0 : 1) + (string.IsNullOrWhiteSpace(clientId) ? 0 : 1) + (string.IsNullOrWhiteSpace(clientSecret) ? 0 : 1); entra = set == 3 ? new SampleEntraDirectory(tenantId!, clientId!, clientSecret!) : null; if (set is > 0 and < 3) { error = $"Entra directory mode is half-configured. Set all of {EntraTenantIdVariable}, {EntraClientIdVariable} and {EntraClientSecretVariable} to back the Access directory with your Entra tenant, or unset all three to use the built-in static directory. See samples/Explorer/README.md."; return false; } error = null; return true; } } ```` ## PeerLink.cs ````csharp using Microsoft.AspNetCore.Http; namespace Orleans.Lattice.Samples.Explorer; /// /// The link between the two regions, and the switch that pauses it so the /// Replication area can show a link going Lagging and then Stalled. /// /// /// Each region's replication receiver runs behind . /// While the link is paused every cross-region replication call - live push, /// snapshot bootstrap and saga control, in both directions - is refused with /// 503 Service Unavailable, which the sender's gRPC client reads as the /// peer being unreachable. Nothing else on the endpoint is touched: the /// Explorer's own facade calls keep working, so the console can watch the /// backlog grow. Resuming lets the senders catch up from where they stopped. /// internal sealed class PeerLink { /// /// The path prefix every cross-region replication gRPC service shares /// (LatticeReplication, LatticeRemoteSnapshot and /// LatticeSaga). The replication control and status facades /// the Explorer calls live under /orleans.lattice.api.replication and /// are never matched. /// public const string ReplicationPathPrefix = "/orleans.lattice.replication."; private readonly Lock _gate = new(); private volatile bool _paused; /// Raised after the link is paused or resumed, with the new state. public event Action? Changed; /// Whether cross-region replication is currently refused. public bool IsPaused => _paused; /// Pauses the link, or resumes it when it is paused. /// Whether the link is paused afterwards. public bool Toggle() { bool paused; lock (_gate) { paused = !_paused; _paused = paused; } Changed?.Invoke(paused); return paused; } /// Pauses the link; does nothing when it is already paused. /// Whether this call paused it. public bool Pause() => Set(paused: true); /// Resumes the link; does nothing when it is not paused. /// Whether this call resumed it. public bool Resume() => Set(paused: false); /// Whether is a cross-region replication call. /// The request path. public static bool IsReplicationPath(PathString path) => path.HasValue && path.Value!.StartsWith(ReplicationPathPrefix, StringComparison.Ordinal); /// /// Refuses a cross-region replication call while the link is paused, and /// passes every other request to . /// /// The request. /// The rest of the pipeline. public Task InvokeAsync(HttpContext context, RequestDelegate next) { ArgumentNullException.ThrowIfNull(context); ArgumentNullException.ThrowIfNull(next); if (_paused && IsReplicationPath(context.Request.Path)) { context.Response.StatusCode = StatusCodes.Status503ServiceUnavailable; return Task.CompletedTask; } return next(context); } private bool Set(bool paused) { lock (_gate) { if (_paused == paused) { return false; } _paused = paused; } Changed?.Invoke(paused); return true; } } ```` ## ReplicationWriter.cs ````csharp using System.Text; namespace Orleans.Lattice.Samples.Explorer; /// /// A small background writer that keeps the replication links busy, so the /// Replication area shows live contact, backlog and health. Each tick it /// overwrites one key per target, cycling through a fixed key set: the trees /// stay the same size however long the sample runs. /// internal sealed class ReplicationWriter : IAsyncDisposable { private readonly IReadOnlyList _targets; private readonly TimeSpan _interval; private readonly CancellationTokenSource _stop = new(); private Task? _loop; private long _ticks; /// Creates a writer; nothing is written until or . /// The trees written, one key each per tick. /// The time between ticks. public ReplicationWriter(IReadOnlyList targets, TimeSpan interval) { ArgumentNullException.ThrowIfNull(targets); ArgumentOutOfRangeException.ThrowIfLessThanOrEqual(interval, TimeSpan.Zero); _targets = targets; _interval = interval; } /// The number of ticks written so far. public long Ticks => Interlocked.Read(ref _ticks); /// The key a target writes on tick : one of its keys, in turn. /// The target. /// The zero-based tick. public static string KeyFor(ReplicationWriterTarget target, long tick) { ArgumentNullException.ThrowIfNull(target); ArgumentOutOfRangeException.ThrowIfNegative(tick); return $"{target.KeyPrefix}{tick % target.KeyCount:D3}"; } /// Starts writing on a timer. Calling it again does nothing. public void Start() => _loop ??= RunAsync(_stop.Token); /// Writes one tick: one key per target. /// Cancels the tick. public async Task WriteOnceAsync(CancellationToken cancellationToken = default) { var tick = Interlocked.Increment(ref _ticks) - 1; var value = Encoding.UTF8.GetBytes($"status-{tick}"); // A trusted co-hosted writer, like the seeding: system-origin bypasses // the deny-by-default gate for this process's own writes. using var _ = LatticeSystemOrigin.Enter(); for (var i = 0; i < _targets.Count; i++) { var target = _targets[i]; await target.Tree.SetAsync(KeyFor(target, tick), value, cancellationToken).ConfigureAwait(false); } } /// public async ValueTask DisposeAsync() { await _stop.CancelAsync().ConfigureAwait(false); if (_loop is not null) { await _loop.ConfigureAwait(false); } _stop.Dispose(); } private async Task RunAsync(CancellationToken cancellationToken) { using var timer = new PeriodicTimer(_interval); try { while (await timer.WaitForNextTickAsync(cancellationToken).ConfigureAwait(false)) { try { await WriteOnceAsync(cancellationToken).ConfigureAwait(false); } catch (Exception exception) when (exception is not OperationCanceledException) { // A write that fails (a silo still starting or already // stopping) is skipped; the next tick tries again. } } } catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested) { // Stopped. } } } ```` ## ReplicationWriterTarget.cs ````csharp namespace Orleans.Lattice.Samples.Explorer; /// One tree the writes, and the fixed key set it cycles through. /// The region the tree is written in. /// The tree. /// The prefix of every key written. /// How many distinct keys are written, in turn; the tree never holds more. internal sealed record ReplicationWriterTarget(string Region, ILattice Tree, string KeyPrefix, int KeyCount) { /// The key set's size, which must be positive. public int KeyCount { get; } = KeyCount > 0 ? KeyCount : throw new ArgumentOutOfRangeException(nameof(KeyCount), KeyCount, "A writer target needs at least one key."); } ```` ## SampleBanner.cs ````csharp using Orleans.Lattice.Membership; using Orleans.Lattice.Samples.Explorer.TaskBoard; namespace Orleans.Lattice.Samples.Explorer; /// The console output a started sample prints: every URL, every sample identity and how to drive the estate. internal static class SampleBanner { /// Writes the banner for a started . /// Where the banner goes. /// The started sample. /// How long the start took. public static void Write(TextWriter writer, ExplorerSample sample, TimeSpan startup) { ArgumentNullException.ThrowIfNull(writer); ArgumentNullException.ThrowIfNull(sample); var estate = sample.West is not null; writer.WriteLine(); writer.WriteLine(estate ? "Orleans.Lattice Explorer sample - two regions, tenancy and replication in one process" : "Orleans.Lattice Explorer sample - one region (--minimal)"); writer.WriteLine($"Started in {startup.TotalSeconds:0.0}s."); writer.WriteLine(); writer.WriteLine("URLs"); writer.WriteLine($" Explorer console {sample.Console.Url} (connected to region '{sample.ConsoleRegion.Id}')"); foreach (var region in sample.Regions) { writer.WriteLine($" Region {region.Id,-11} gRPC {region.Plan.GrpcEndpoint} (silo port {region.Plan.SiloPort}, gateway port {region.Plan.GatewayPort})"); } writer.WriteLine(); writer.WriteLine(sample.Console.SignInAs is { } signInAs ? $"Sample identities (any password signs in; the console signs in as '{signInAs}' automatically - {ExplorerSampleOptions.SignInAsSwitch} picks another)" : $"Sample identities (any password signs in; the console starts signed out - use its Sign in dialog)"); writer.WriteLine($" {SampleIdentities.Administrator,-15} bootstrap administrator and platform operator: every area"); if (estate) { writer.WriteLine($" {SampleIdentities.AcmeAdmin,-15} tenant admin of '{SampleIdentities.AcmeTenant}': the tenant-scoped view at /t/{SampleIdentities.AcmeTenant}"); writer.WriteLine($" {SampleIdentities.GlobexAdmin,-15} tenant admin of '{SampleIdentities.GlobexTenant}': the tenant-scoped view at /t/{SampleIdentities.GlobexTenant}"); } writer.WriteLine($" {SampleIdentities.Alice,-15} groups '{SampleIdentities.OperatorsGroup}' and '{SampleIdentities.TaskEditorsGroup}'"); writer.WriteLine($" {SampleIdentities.Bob,-15} group '{SampleIdentities.TaskViewersGroup}'"); writer.WriteLine($" {SampleIdentities.Carol,-15} group '{SampleIdentities.VisitorsGroup}'"); writer.WriteLine(sample.Options.Entra is null ? " Identity directory: static in-memory roster - the Access create form fails closed on any id not in it." : " Identity directory: Microsoft Entra (Graph) - the Access picker and validated create use your tenant."); writer.WriteLine(sample.Options.GroupMergeMode == SubjectGroupMergeMode.TokenOnly ? " Group-merge mode: TokenOnly - local membership is inert, so Access renders group editing disabled." : $" Group-merge mode: {sample.Options.GroupMergeMode} - set LATTICE_MEMBERSHIP_MERGE_MODE=TokenOnly to see merge-mode gating."); writer.WriteLine(); writer.WriteLine("Seeded"); foreach (var line in sample.SeedLog) { writer.WriteLine(" " + line); } writer.WriteLine(); writer.WriteLine($"The '{TaskBoardApp.Slug}' app is in Apps > Catalogue; see samples/Explorer/Apps/TaskBoard/README.md."); writer.WriteLine("Telemetry is hidden: it needs a Prometheus-compatible metrics backend, which this sample does not run."); if (estate) { writer.WriteLine($"A background writer updates '{SampleIdentities.FactoryFloorTree}' in both regions every {sample.Options.WriterInterval.TotalSeconds:0.#}s."); writer.WriteLine(sample.PeerLink.IsPaused ? "The peer link is PAUSED (--peer-paused): links go Lagging, then Stalled. Press P to resume it." : "Press P to pause the peer link (links go Lagging, then Stalled) and P again to resume it."); writer.WriteLine($"Run with {ExplorerSampleOptions.ExplorerRegionSwitch} {SampleIdentities.WestRegion} to point the console at the west region, or {ExplorerSampleOptions.MinimalSwitch} for one region."); } writer.WriteLine("Press Ctrl+C to stop."); } } ```` ## SampleCircuitDiagnostics.cs ````csharp using Microsoft.AspNetCore.Components.Server; using Microsoft.Extensions.Logging.Console; namespace Orleans.Lattice.Samples.Explorer; /// /// Makes a console circuit fault diagnosable (issue #4011). The sample keeps its console /// quiet - it clears every logging provider - so a circuit the framework terminated used /// to leave nothing behind but the browser's "unhandled exception on the current circuit". /// The console region now writes exactly one kind of record to the terminal: Blazor's own /// Error record of an unhandled circuit exception, with its stack trace. In Development /// the browser is also sent the detail (). /// /// /// The record is the framework's, carrying the exception and the circuit id; the sample /// adds no message of its own and logs no user input. /// internal static class SampleCircuitDiagnostics { /// The category prefix Blazor Server logs circuit faults under. public const string CircuitCategory = "Microsoft.AspNetCore.Components.Server.Circuits"; /// Adds the terminal log of circuit faults, and nothing else, to a region's logging. /// The console region's logging, with every provider already cleared. public static void ConfigureLogging(ILoggingBuilder logging) { ArgumentNullException.ThrowIfNull(logging); logging.AddSimpleConsole(console => console.ColorBehavior = LoggerColorBehavior.Disabled); logging.SetMinimumLevel(LogLevel.None); logging.AddFilter(CircuitCategory, LogLevel.Error); } /// In Development, sends a circuit fault's detail to the browser as well. /// The console region's services. /// The console region's environment. public static void ConfigureCircuits(IServiceCollection services, IHostEnvironment environment) { ArgumentNullException.ThrowIfNull(services); ArgumentNullException.ThrowIfNull(environment); if (environment.IsDevelopment()) { services.Configure(circuit => circuit.DetailedErrors = true); } } } ```` ## SampleConsolePlan.cs ````csharp namespace Orleans.Lattice.Samples.Explorer; /// Where the Explorer console is served, which region's gRPC endpoint it dials and who it signs in as. /// The HTTP port the console is served on. /// The gRPC endpoint of the region the console connects to. /// The console's persisted configuration file. /// The identity the console signs in as automatically, or for none. internal sealed record SampleConsolePlan(int WebPort, Uri Endpoint, string ConfigPath, string? SignInAs = SampleIdentities.Administrator) { /// The console's address. public Uri Url => new($"http://localhost:{WebPort}/"); } ```` ## Remaining files This sample is too large to inline in full. The remaining 29 file(s) are in the repository: - [SampleEntraDirectory.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/SampleEntraDirectory.cs) - [SampleExplorerEnvironment.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/SampleExplorerEnvironment.cs) - [SampleIdentities.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/SampleIdentities.cs) - [SamplePorts.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/SamplePorts.cs) - [SampleRegion.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/SampleRegion.cs) - [SampleRegionPeer.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/SampleRegionPeer.cs) - [SampleRegionPlan.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/SampleRegionPlan.cs) - [SampleSeeder.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/SampleSeeder.cs) - [SampleSharedBackupSink.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/SampleSharedBackupSink.cs) - [test/ConsoleCircuit.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/test/ConsoleCircuit.cs) - [test/DemoBasicAuthenticatorTests.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/test/DemoBasicAuthenticatorTests.cs) - [test/DirectorySpine.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/test/DirectorySpine.cs) - [test/EstateSmokeTests.Apps.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/test/EstateSmokeTests.Apps.cs) - [test/EstateSmokeTests.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/test/EstateSmokeTests.cs) - [test/EstateSmokeTests.Tenancy.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/test/EstateSmokeTests.Tenancy.cs) - [test/EstateSmokeTests.TenantSwitcher.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/test/EstateSmokeTests.TenantSwitcher.cs) - [test/Explorer.Tests.csproj](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/test/Explorer.Tests.csproj) - [test/ExplorerSampleOptionsTests.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/test/ExplorerSampleOptionsTests.cs) - [test/MinimalSmokeTests.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/test/MinimalSmokeTests.cs) - [test/PeerLinkTests.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/test/PeerLinkTests.cs) - [test/ReplicationWriterTests.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/test/ReplicationWriterTests.cs) - [test/SampleCircuitDiagnosticsTests.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/test/SampleCircuitDiagnosticsTests.cs) - [test/SampleExplorerEnvironmentTests.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/test/SampleExplorerEnvironmentTests.cs) - [test/SamplePortsTests.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/test/SamplePortsTests.cs) - [test/SampleRegionPlanTests.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/test/SampleRegionPlanTests.cs) - [test/SampleSeederTests.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/test/SampleSeederTests.cs) - [test/SampleSharedBackupSinkTests.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/test/SampleSharedBackupSinkTests.cs) - [test/SampleTestHost.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/test/SampleTestHost.cs) - [test/TenancyRegionsSmokeTests.cs](https://github.com/NSTA1/Orleans.Lattice/blob/release/9.9/samples/Explorer/test/TenancyRegionsSmokeTests.cs)