Backend services are small, self-contained, and (ideally) stateless applications that can be deployed and scaled independently. They are designed to be used in conjunction with other services and are often packaged together to form a larger application.
+The following is an example for the combination of services creating the backend of a Telestion application:
+graph TB
+ accTitle: Diagram showcasing the structure of an exemplary Telestion backend. Text description in collapsible section below.
+ db[Database]
+ md[Mission Device]
+ subgraph Backend
+ io[IO Service]
+ tmps[Telemetry Parser Service]
+ tcs[Telecommand Service]
+ dbs[Database Writer Service]
+ dbqs[Database Query Service]
+ end
+ subgraph Frontend
+ wc[Web Client]
+ end
+ md <---> io
+ io --> tmps
+ tmps --> dbs
+ dbs --> db
+ wc --> dbqs
+ dbqs --> db
+ wc --> tcs
+ tcs --> ioThe most common way to write a backend service is to use TypeScript.
+Get started writing a backend service in TypeScript
+However, for some use cases, it may be necessary to write a backend service in other languages.
+Even some of the core services provided out of the box are written in Rust. To learn how to write a service in Rust, see Using Rust.
+You can even write a backend service in any language you want. The only requirement is that it can communicate with the NATS message bus. To learn how to write a service in other languages, see Using other languages.
+ + + + + + + + + + + + + + + + +You can use any language you want to write your backend. The only requirement is that it can communicate with the NATS message bus.
+The only technical requirement for a backend service is that it can communicate with the NATS message bus. This means that it must be able to send and receive messages on the message bus.
+However, there are some additional standards that you should follow to make your service easier to use (and compliant with the Telestion ecosystem):
+Your service should be deployable as both a Docker container and as an executable. This makes it easier to deploy and scale your service.
+Your service should be configurable via environment variables.
+Every Telestion service receives at least the following environment variables:
+NATS_URL: The URL of the NATS serverNATS_USER: The username of the NATS userNATS_PASSWORD: The password of the NATS userSERVICE_NAME: The name of the service. This is used to create a unique queue group for your service. See Queues for more information.DATA_DIR: The path to the data directory. This is where your service should store any data it needs to persist. This is shared between multiple services. To ensure that your service doesn’t overwrite data from other services, you should create a subdirectory for your service.If your service doesn’t receive any of these environment variables, it should exit with a non-zero exit code.
+Warning
+There can be multiple instances of a service with the same name running at the same time. They are guaranteed to have the same configuration, apart from the SERVICE_ID. If you need a truly unique identifier, you can combine the SERVICE_NAME and the process ID.
Your service should log any “feedback” to stdout and stderr.
For logging data to files, you should use the Standard Operations Library.
+NATS allows you to create queue groups. This means that you can have multiple instances of the same service running, and they’ll share the messages they receive.
+If you want to use this feature, you should use the SERVICE_NAME environment variable to create a unique queue group for your service.
Your message must be able to handle, without crashing, the following types of messages:
+Your service mustn’t assume anything about the format or content of the message body. It must be able to handle any message body of the two types.
+Your service should provide a health check feature on the message bus subject __telestion__/health. This allows other services to check if your service is still running.
While running, any Telestion service should respond (within 0.5 seconds) to requests on the __telestion__/health subject with a message containing the following JSON-encoded information:
{
+ "errors": 0, // or number of "recent" errors
+ "service": "my-service", // the SERVICE_ID
+ "name": "My Service" // the SERVICE_NAME
+}
+Info
+The standard operations library is a library that provides a set of common operations that are used by many Telestion services. While it can be overwritten, every Telestion application comes with an implementation of these operations out-of-the-box that you can use.
+The standard operations library provides a simple way to log data to files.
+To use it, publish a message to the __telestion__/log/[category] subject with the body you want to log. [category] is the category of the log message. It can be any string.
The standard operations library then logs the message to the file logs/[category].log in your data directory.
use nats::asynk::Connection;
+use std::error::Error;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn Error>> {
+ let nc = Connection::new("nats://localhost:4222").await?;
+ let sub = nc.subscribe("bar")?.with_handler(move |msg| {
+ println!("Received {}", &msg);
+ Ok(())
+ });
+
+ Ok(())
+}
+Tip
+Not every service needs to be configurable. If you are writing a simple service, you can skip this section.
+However, you can often save yourself a lot of time by making your service configurable. This way, you can use the same service in multiple environments without having to change the code.
+Warning
+This section is specific to TypeScript services. Only the environment variables are standardized and must be implemented for all Telestion services.
+While services in other languages can use the same configuration sources, they aren’t required to do so.
+Services can be configured using the following sources:
+All these sources get combined into a single configuration object. If a configuration value is defined in multiple sources, the following order is used:
+Environment variables are the most common way to configure a service. They are easy to use and supported by most platforms.
+Environment variables are always strings. If you need to use a different type, you will have to parse the value yourself.
+Command line arguments are useful for configuring a service during development. They are also useful for overriding configuration values when running a service in production.
+Configuration files are useful for configuring a service in production. They are also useful for overriding configuration values when running a service in production.
+Configuration files are optional. If no configuration file is provided, the service will still start.
+A configuration file is a JSON file with an object as its root element. The keys of this object are the configuration values. The values of this object are the configuration values.
+The configuration file is loaded from the path passed as CONFIG_FILE as either environment variable or command line argument.
You can optionally also pass a CONFIG_KEY to load a specific key from the configuration file. This is useful if you want to use the same configuration file for multiple services.
graph TB
+ accTitle: Diagram of the configuration sources and their order of precedence. Text description in collapsed section below.
+ A[Environment Variables] --merged into--> C[Preliminary Configuration]
+ B[Command line arguments] --merged into with priority--> C
+ C -.CONFIG_FILE.-> D[Configuration File]
+ D --merged into--> E[Configuration Object]
+ C --merged into with priority--> EConfiguration sources and their order of precedence.
+CONFIG_FILE parameter of the preliminary configuration) and merged into the preliminary configuration.Some configuration values are required for all services. These values are:
+NATS_URL: The URL of the NATS server to connect to.NATS_USER: The username to use when connecting to NATS.NATS_PASSWORD: The password to use when connecting to NATS.SERVICE_NAME: The name of the service. This is used to identify the service in the logs and in the NATS server. This is required for all services.DATA_DIR: The directory where the service can store data. This is required for all services.Tip
+To make it easier to run your service during development, sensible defaults are used when you pass the --dev flag to the service:
| Configuration Value | +Default Value | +
|---|---|
NATS_URL |
+localhost:4222 |
+
NATS_USER |
+(none) | +
NATS_PASSWORD |
+(none) | +
SERVICE_NAME |
+dev-[process gid] |
+
DATA_DIR |
+./data |
+
This way, you don’t have to set all the required configuration values when running the service locally.
+Without the --dev flag, the service fails if any of the required configuration values are missing.
Now that you know about the different configuration sources, let’s see how you can access the configuration in your service. Since the complicated bits are handled by the startService function, this is actually pretty straight forward.
Create a file called config.json next to your service.ts file with the following content:
{
+ "SERVICE_NAME": "Config Tester",
+ "tasks": {
+ "task1": "Task 1",
+ "task2": "Task 2"
+ }
+}
+Now, let’s adjust the service.ts file to use the configuration:
import { startService } from "https://deno.land/x/telestion/mod.ts";
+import { z } from "https://deno.land/x/zod@v3.21.4/mod.ts";// (1)!
+
+const { config: rawConfig/* (2)! */} = await startService({
+ nats: false,
+});
+
+const config = z.object({
+ NAME: z.string(),
+ tasks: z.record(z.string(), z.string()),
+}).parse(rawConfig);// (3)!
+
+console.log(config.NAME, config.tasks);// (4)!
+z function from the Zod to validate the configuration. Never assume the configuration is valid. Always validate it before using it.rawConfig.Now, let’s see what happens if we run the service:
+ +As expected, the service doesn’t start:
+$ deno run --allow-all service.ts --dev
+Running in development mode.
+Using default values for missing environment variables.
+error: Uncaught ZodError: [
+ {
+ "code": "invalid_type",
+ "expected": "string",
+ "received": "undefined",
+ "path": [
+ "NAME"
+ ],
+ "message": "Required"
+ },
+ {
+ "code": "invalid_type",
+ "expected": "object",
+ "received": "undefined",
+ "path": [
+ "tasks"
+ ],
+ "message": "Required"
+ }
+]
+Let’s fix this by passing the required configuration values:
+deno run --allow-all service.ts --dev \
+ --CONFIG_FILE ./config.json \ # (1)!
+ --NAME "Hello" # (2)!
+--CONFIG_FILE flag.NAME configuration value using the --NAME flag.Now, everything works as expected.
+ + + + + + + + + + + + + + + + +Note
+The author generated this text in part with GPT-3, OpenAI’s large-scale language-generation model. Upon generating draft language, the author reviewed, edited, and revised the language to their own liking and takes ultimate responsibility for the content of this publication.
+This tutorial will explain step-by-step how to write a log service that will listen for messages on the log.> subject and write them to a file.
First, we need to import the startService function from our library (lib.ts) and the encode function from the standard Deno library.
Next, we create a new TextEncoder instance. This will be used to turn messages into a format that can be written to a file.
+ +We then call the startService function to set up our service. This will return an object containing information about the message bus that we can use to subscribe to messages.
We then subscribe to the message bus, using a wildcard subscription for any messages published on the log.> subject. This will allow us to receive all messages published on any topics starting with log..
We use a for-await-of loop to receive messages from the message bus. For each message, we extract the subject (split the string on ., then take the second element) and the message data, which we encode using the encode function from the standard library.
We log the message to the console and write it to a file (appending it to the end).
+ +And that’s it! Our service is now complete and ready to be used.
+import { startService } from "https://deno.land/x/telestion/mod.ts";
+import { encode } from "https://deno.land/std@0.186.0/encoding/hex.ts";
+
+const encoder = new TextEncoder();
+
+const { messageBus } = await startService();
+
+const logMessages = messageBus.subscribe("log.>");
+
+for await (const msg of logMessages) {
+ try {
+ const currentTime = new Date().toISOString();
+ const logMessage = encode(msg.data).toString();
+ const subject = msg.subject.split(".")[1];
+
+ console.log(`${currentTime} [${subject}] ${logMessage}`);
+ await Deno.writeFile(
+ "log.txt",
+ encoder.encode(`${currentTime} [${subject}] ${logMessage}\n`),
+ { append: true },
+ );
+ } catch (error) {
+ console.error(error);
+ }
+}
+TypeScript is the recommended language for writing backend services. It is a superset of JavaScript that adds static typing and other features that make it easier to write and maintain code.
+To write a backend service in TypeScript, you should be familiar with JavaScript and (ideally) TypeScript. Overall, basic JavaScript knowledge will be sufficient to get started, but async/await and Promises are used extensively for services, so you should be familiar with these topics.
Deno is a JavaScript/TypeScript runtime that is built on top of V8, Rust, and Tokio. It is a secure runtime for JavaScript and TypeScript.
+Compared to Node.js, Deno has the following advantages:
+To install Deno, please follow the instructions on the Deno website .
+Create a new directory for your service:
+ +Create a new file called service.ts:
Open service.ts in your favorite editor and add the following code:
import { startService } from 'https://deno.land/x/telestion/mod.ts';// (1)!
+
+await startService/*(2)!*/({
+ nats: false,// (3)!
+});
+
+console.log('Hello World!');// (4)!
+startService function from the library. Note that the library is in the same directory as the service.ts file, so we can use a relative path.+ Later, when we publish the library to a registry, we will be able to use a URL instead.
To run the service, run the following command:
+ +Success
+You should see the following output:
+ +Running in development mode
+When you run the service with the --dev flag, the service will use default values for missing environment variables. You’ll learn more about this in the configuration section.
Now that you have a basic service running, you should have a look at how to make your service configurable.
+ + + + + + + + + + + + + + + + + +The message bus is a simple, lightweight, and fast way to send messages between different parts (services) of your application. It is a simple publish/subscribe system that allows you to send messages to a specific subject and have any listeners on that subject receive the message.
+Running NATS for development
+Now that we want to interact with the message bus, we need to have NATS running. If you’re using the --dev mode for testing your service, it’s sufficient to run the nats-server executable in a separate terminal window. This will start a local NATS server on port 4222 which is the default port for NATS.
If you have a prdouction-like setup, you’ll need to pass the NATS_USER and NATS_PASSWORD corresponding to your NATS configuration as configuration parameters to your service for authentication.
Connecting to the event bus is automatically handled by the startService function. It will connect to the message bus using the NATS_URL environment variable. If you’re running the service in --dev mode, this will be nats://localhost:4222 by default.
All you need to do compared to the previous examples is to omit the { nats: false } parameter from the startService function call:
import {
+ startService
+} from "https://deno.land/x/telestion/mod.ts";
+
+const {nc/* (1)! */} = await startService(/* (2)! */);
+nc for later use.{ nats: false } parameter from the startService function call since we want to connect to the message bus.Note
+startService actually returns an object containing the NATS connection (nc) and a few other things. In our example, we use destructuring to only get the nc variable. This is equivalent to the following code:
Publishing messages is as simple as calling the publish function on the NATS connection:
However, Telestion Hub uses a specific message format for all messages sent over the message bus. A message can be either JSON or a binary message. The binary message is used for sending large amounts of data, e.g., images or video streams. The JSON message is used for all other messages.
+To send a JSON message, you need to create a JSON object and pass it to the publish function:
import {
+ JSONCodec,
+ startService
+} from "https://deno.land/x/telestion/mod.ts";
+// or: import { JSONCodec } from "https://deno.land/x/nats/src/mod.ts";
+
+const {nc} = await startService();
+
+const jsonCodec = JSONCodec();//(2)!
+
+await nc.publish("subject", jsonCodec.encode/*(3)!*/({
+ foo: "some arbitrary JSON-compatible data",
+ bar: 42
+}));
+JSONCodec (for convenience, this gets re-exported by the lib.ts, but you can also import it directly from the NATS library).JSONCodec instance.JSONCodec instance.To send a binary message, you need to create a Uint8Array containing the bytes and pass it to the publish function:
import {
+ startService
+} from "https://deno.land/x/telestion/mod.ts";
+
+const {nc} = await startService();
+
+await nc.publish("subject", new Uint8Array([0x01, 0x02, 0x03]));
+Uint8Arrays
+You can learn more about how you can use Uint8Array on MDN.
There are multiple ways to subscribe to messages on a subject. The most common way is to use the subscribe function in combination with a for await loop:
import {
+ startService
+} from "https://deno.land/x/telestion/mod.ts";
+
+const {nc} = await startService();
+
+const subjectSubscription/*(1)!*/ = await nc.subscribe("subject"/*(2)!*/);
+
+for await (const message of subjectSubscription) {//(3)!
+ console.log(message.data);//(4)!
+}
+subjectSubscription for later use.subject subject.Unfortunately, this won’t decode our JSON messages automatically. We need to do this ourselves:
+import {
+ JSONCodec,
+ startService
+} from "https://deno.land/x/telestion/mod.ts";
+
+const {nc} = await startService();
+
+const jsonCodec = JSONCodec();
+
+const subjectSubscription = await nc.subscribe("subject");
+for await (const message of subjectSubscription) {
+ const jsonMessage = jsonCodec.decode(message.data);//(1)!
+ console.log(jsonMessage.foo);//(2)!
+}
+JSONCodec instance.foo property of the decoded JSON message to the console.Danger
+Can you spot the problem with this code? What happens if the message data doesn’t contain a foo property? Or if it’s not a JSON message at all? This would lead to our service crashing!
Never assume a message’s structure!
+You should always validate the message data before using it. We’ll cover this in the next section.
+A Telestion service must validate all messages it receives. This is to ensure that the service doesn’t crash when it receives invalid messages.
+The first “layer” of validation is the message type. A message can either be a JSON message or a binary message. The jsonCodec.decode function will throw an error if the message data is not a valid JSON message. Therefore, we can use a try/catch block to catch the error and handle it accordingly:
// ...
+
+for await (const message of subjectSubscription) {
+ try/*(3)!*/{
+ const jsonMessage = jsonCodec.decode(message.data);
+ console.log(jsonMessage.foo);
+ } catch (_e) {
+ console.error/*(2)!*/("Received invalid message:", message);
+ }
+}
+jsonCodec.decode.try/catch block.Binary Messages
+Since any messages get sent as binary messages (in fact, the JSONCodec does nothing else than convert the JSON message to a Uint8Array and back), there’s no way to validate that a message is supposed to be a binary message. This makes the next section even more important.
The second “layer” of validation is the message structure. This is where you validate that the message data contains all the properties you expect it to contain. For example, if you expect a message to contain a foo property, you must verify its existence before using it.
For structured JSON data, we recommend that you use the zod library for validation. This is also used in our lib.ts file to validate the configuration. You can find more information about zod in the library’s GitHub repository.
Let’s create a zod schema for our JSON message in a new file called foo-message.ts:
import {
+ z
+} from "https://deno.land/x/zod@v3.16.1/mod.ts";
+
+export const fooMessageSchema = z.object/*(1)!*/(({
+ foo: z.string()/*(2)!*/,
+ bar: z.number().min(-10)/*(3)!*/
+});
+
+export type FooMessage = z.infer<typeof fooMessageSchema>;//(4)!
+FooMessage must be an object.FooMessage must have a foo property that is a string.FooMessage must have a bar property that is a number and is greater than or equal to -10.FooMessage type. While we won’t use it in this example, it’s good practice to create a type for each schema you create. This allows you to use the type anywhere in your code:
+ Now we can use this schema to validate the message data:
+import {
+ fooMessageSchema
+} from "./foo-message.ts";
+
+// ...
+
+for await (const message of subjectSubscription) {
+ try {
+ const jsonMessage = fooMessageSchema.parse/*(1)!*/(
+ jsonCodec.decode(message.data)
+ );
+
+ console.log(jsonMessage/*(2)!*/.foo);
+ } catch (_e) {
+ console.error("Received invalid message:", message);
+ }
+}
+fooMessageSchema schema. This will throw an error if the message data doesn’t match the schema.jsonMessage is a valid FooMessage object. Therefore, we can access the foo property without any problems.Success
+If your editor has great TypeScript support and has shown you warnings/errors before, they are now gone! This is because TypeScript now knows that the jsonMessage variable is a valid FooMessage object. In other words, your code is now safe from invalid messages!
Binary Messages
+For binary messages, you can’t use zod to validate the message structure. Instead, you should use the Uint8Array methods to validate the message structure. For example, you can check the length of the message data using the length property of the Uint8Array:
However, the exact validation required completely depends on your use case. Just make sure that your code doesn’t crash when it receives an invalid message.
+So far, we’ve used the for await loop. This is a convenient way to subscribe to a single topic. However, if you want to do more than just react to messages from a specific subject, we get into trouble. Since the for await loop is blocking, we can’t do anything else while we’re waiting for messages.
We can solve this by wrapping the for await loop in an async function and calling it in a separate thread. This allows us to do other things while we’re waiting for messages:
// ...
+
+const subjectMessages = nc.subscribe("foo");
+(async () => {//(1)!
+ for await (const message of subjectMessages) {
+ // Handle messages from the "foo" subject
+ }
+})();
+
+// ... (2)
+for await loop in an async function and call it immediately. This will start the subscription in parallel to the rest of the code. Note that we’re storing the return value of nc.subscribe in a variable outside the async function. This is important so that we can close the subscription or check its status later.
Closing the Subscription
+You can close the subscription by calling the unsubscribe method on the subscription object:
You must call unsubscribe on the subscription object. Calling nc.unsubscribe will unsubscribe from all subscriptions!
This now allows us to subscribe to multiple topics:
+// ...
+
+const fooMessages = nc.subscribe("foo");//(1)!
+(async () => {
+ for await (const message of fooMessages) {
+ // Handle messages from the "foo" subject
+ }
+})();
+
+const barMessages = nc.subscribe("bar");//(2)!
+(async () => {
+ for await (const message of barMessages) {
+ // Handle messages from the "bar" subject
+ if (shouldUnsubscribeFoo(message))
+ fooMessages.unsubscribe/*(3)!*/();
+
+ if (shouldUnsubscribeBar(message))
+ barMessages.unsubscribe/*(4)!*/();
+ }
+})();
+
+await Promise.all/*(5)!*/([
+ fooMessages.closed,
+ barMessages.closed
+]);
+
+console.log("All subscriptions closed!");//(6)!
+foo subject.bar subject (in parallel to the foo subscription).foo subject if the shouldUnsubscribeFoo function returns true.bar subject if the shouldUnsubscribeBar function returns true.unsubscribe method is called on the subscription object. The closed property is a Promise that resolves when the subscription is closed.
Promise.all is a convenient way to wait for multiple promises to resolve. It returns a Promise that resolves when all promises passed to it have resolved.
Info
+Queue groups are a way to distribute messages between multiple subscribers. If you have multiple subscribers to a subject, you can use queue groups to distribute messages between them. This is useful if you want to distribute messages between multiple instances of a service (for example, if you want to scale your service horizontally because processing a message takes too long).
+All you have to do to use queue groups is to pass a queue option to the subscribe method. You can use any string as the queue name, but by its definition, the SERVICE_NAME configuration parameter works perfect for this. For convenience, this gets exposed as serviceName on the object returned by startService:
// ...
+
+const {
+ nc,
+ serviceName/*(1)!*/
+} = await startService();
+
+const fooMessages = nc.subscribe(
+ "foo",
+ {queue: serviceName/*(2)!*/}
+);
+(async () => {
+ for await (const message of fooMessages) {
+ // Handle messages from the "foo" subject
+ }
+})();
+
+// ...
+serviceName from the object returned by startService.serviceName as the queue option to the subscribe method.If you now run multiple instances of your service, you’ll see that messages are distributed between them. This is because the queue option tells the message bus to distribute messages between all subscribers with the same queue name.
Service names in development mode
+When you run your service in development mode, the serviceName will be generated. This means that you’ll get a different service name every time you start your service. To avoid this, you can either set the SERVICE_NAME environment variable or pass a service name via the CLI:
Wildcards are a way to subscribe to multiple subjects at once. This is useful if you want to subscribe to multiple subjects that have a common prefix. For example, you could have a service that handles all requests to the /api endpoint. You could then subscribe to all requests to the /api endpoint by subscribing to the api.> subject.
There are two types of wildcards: * and >. The * wildcard matches a single token. The > wildcard matches one or more tokens. For example, the api.* subject matches api.foo and api.bar, but not api.foo.bar. The api.> subject matches api.foo, api.bar, and api.foo.bar.
You can use wildcards in the subscribe method and then use the subject property of the message to check which subject the message was sent to:
// ...
+
+/**
+ * A simple key-value store.
+ */
+const store: Record<string, unknown> = {};
+
+const kvMessages = nc.subscribe/*(1)!*/("kv.>");
+(async () => {
+ for await (const message of kvMessages) {
+ try {
+ const [_kv, action, ...keyParts] =
+ message.subject.split/*(2)!*/(".");
+
+ const key = keyParts.join(".");
+
+ if (action === "get") {
+ // retrieve the value from the store
+ message.respond(
+ jsonCodec.encode(store[key])
+ );
+ } else if (action === "set") {
+ // set the value in the store
+ store[key] = jsonCodec.decode(message.data);
+ message.respond(jsonCodec.encode({ok: true});
+ }
+ } catch (error) {
+ message.respond(
+ jsonCodec.encode({error: error.message})
+ );
+ }
+ }
+})();
+kv.> subject. This matches all subjects that start with kv..kv, the second token is the action, and the rest of the tokens are the key. We store these into variables using array destructuring.In this example, we subscribe to the foo.* subject. We then use the subject property of the message to check which action was requested. If the action is get, we get the value from the store object and respond with it. If the action is set, we set the value in the store object.
For example, if we send a message to the foo.get.bar subject, we’ll get the value of the bar key in the store object. If we send a message to the foo.set.bar subject with the value 42, we’ll set the value of the bar key in the store object to 42.
Success
+Woohoo! You’ve just re-implemented a key-value store using the message bus, which (with a few convenience features on top) is an essential part of Telestion’s standard services! 
So far, we’ve looked at publishing messages and subscribing to messages. However, there’s one more thing we can do with the message bus: request/reply.
+Request/reply is a pattern where one service sends a request to another service and waits for a response. This is useful if you want to get data from another service. For example, you could have a service that stores data in a database. Other services can then request data from this service.
+Let’s start by looking at how we can send a request. We can use the request method on the NatsConnection object to send a request. This makes it incredibly easy to send a request:
// ...
+
+const response = await nc.request/*(1)!*/(
+ "fooRequest"/*(2)!*/,
+ jsonCodec.encode({foo: "bar"})/*(3)!*/
+);
+console.log(response.data);
+request method on the NatsConnection object. This method returns a Promise that resolves when the response is received. The response has the same form as the messages we’ve already seen in our for await loops.jsonCodec codec. This is the same as we’ve done before.Tip: Specifying a timeout
+As it is, our code will wait forever for a response. This is probably not what we want. We can specify a timeout by passing a second argument to the request method:
const response = await nc.request(
+ "fooRequest",
+ jsonCodec.encode({foo: "bar"}),
+ {timeout: 1000}
+);
+This will cause the request method to reject the Promise if no response is received within 1000 milliseconds. Make sure to handle the rejection by handling it appropriately.
Now that we know how to send a request, let’s look at how we can handle a request. We can use the subscribe method on the NatsConnection object to subscribe to a subject. This allows us to handle requests:
// ...
+
+const requestMessages = nc.subscribe/*(1)!*/("fooRequest");
+
+(async () => {
+ for await (const message of requestMessages) {//(2)!
+ message.respond/*(3)!*/(jsonCodec.encode({bar: "baz"}));
+ }
+})();
+fooRequest subject as usual.fooRequest subject as usual.respond method on the message object. This method takes a single argument: the response message data. This is the same as we’ve done before.Tip
+The message received from the fooRequest subject is the same as the message received from the foo subject. This means that we can use the same steps to handle the message as we’ve done before if we need the data to handle the request.
While we’ve covered the basics of interacting with the message bus in this article, there are a few more things you can do with the message bus. You can find more information about the message bus in the NATS documentation. While the connection to the message bus is handled by the startService function, topics like receiving and sending messages are covered more extensively (including useful concepts like request/reply, queue groups, etc.) in the NATS documentation.
This document describes the pre-requisites for deploying Telestion on your local machine.
+Docker is a containerization platform that allows you to package your application and all its dependencies together in the form of containers to ensure that your application works seamlessly in any environment be it development or test or production.
+Docker Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application’s services. Then, with a single command, you create and start all the services from your configuration.
+Info
+Kubernetes is not required for deploying Telestion. It’s mostly relevant for big production deployments.
+Kubernetes is an open source container-orchestration system for automating computer application deployment, scaling, and management.
+Info
+For Telestion, a web server is required to serve the frontend application to the user.
+A web server is server software, or hardware dedicated to running said software, that can satisfy web client requests. A web server can, in general, contain one or more websites. A web server processes incoming network requests over HTTP and several other related protocols.
+Info
+Telestion uses NATS as a message broker. It’s required for the communication between the Telestion services (both backend and frontend).
+NATS is a simple, secure and high-performance open source messaging system for cloud native applications, IoT messaging, and microservice architectures.
+ + + + + + + + + + + + + + + + +Deployment is the process of making a software system available for use. In the context of Telestion, deployment refers to the process of making the Telestion application available for use.
+Warning
+The deployment process is heavily dependent on the specific use case. The following documentation is intended to give a general overview of the deployment process that’s available by default in new Telestion Projects.
+Depending on your project, you may need to adapt the deployment process to your specific needs.
+Telestion can be deployed in multiple ways:
+ +Info
+The local deployment is the easiest way to get started with Telestion. You should probably start with the local deployment and then move on to the other deployment methods as needed.
+Telestion uses NATS as a message broker. NATS is a lightweight, high-performance cloud native messaging system. It is used for the communication between the Telestion backend and the Telestion frontend.
+No matter which deployment method you choose, you need to configure NATS. The configuration of NATS is described in the NATS Configuration document.
+ + + + + + + + + + + + + + + + +Telestion can be deployed locally on your machine. This can have several reasons, for example:
+Note
+It’s a common tactic to have most Telestion services running in a cloud environment and only the services that need direct access to the machine running locally.
+This is easy to achieve thanks to NATS and means that you can have the best of both worlds.
+NATS isn’t complicated to deploy. This guide will show you how to deploy NATS locally.
+Download the NATS server from the NATS download page.
+Run the NATS server with the following command:
+ +NATS can be configured using a configuration file. To run NATS with a configuration file, use the following command:
+ +Info
+This guide will focus on getting you started. We’ll look deeper into NATS permissions in the NATS configuration guide.
+In your NATS configuration file, add the following section:
+authorization {
+ default_permissions = {
+ publish = []
+ subscribe = ["__telestion__.>"]
+ }
+ SERVICE = {
+ publish = ["altitude", "log.>"]
+ subscribe = ["altitude", "__telestion__.health"]
+ allow_responses = true
+ }
+ users = [
+ {user: service, password: service, permissions: $SERVICE}
+ ]
+}
+This will create a user called service with the password service. This user will be able to publish to the altitude subject and subscribe to the __telestion__.health subject.
(coming soon)
+pup¶The process manager pup is a tool that can be used to run multiple services at once without having to manually start each service. It also makes it easy to manage the running services.
pup¶Install pup using the following command:
pup¶In your project’s root directory, create a file called pup.jsonc with the following contents:
{
+ "services": [
+ {
+ "name": "service1",
+ "command": "deno run --allow-net --allow-env service1.ts",
+ "env": {
+ "SERVICE_NAME": "service1",
+ "NATS_URL": "nats://localhost:4222",
+ "NATS_USER": "service",
+ "NATS_PASSWORD": "service"
+ }
+ },
+ {
+ "name": "service2",
+ "command": "deno run --allow-net --allow-env service2.ts",
+ "env": {
+ "SERVICE_NAME": "service1",
+ "NATS_URL": "nats://localhost:4222",
+ "NATS_USER": "service",
+ "NATS_PASSWORD": "service"
+ }
+ }
+ ]
+}
+pup¶Run pup using the following command:
This will start the pup runner. To start the services, run the following command:
+ +Tip
+If you want to have a service starting immediately after the runner starts, you can add "autostart": true to that service’s configuration.
To stop the services, run the following command:
+ +Tip
+You can also stop a single service by specifying its name instead of all.
You can get the status of the services using the following command:
+ +Tip: Running NATS through pup
You can even run NATS through pup. Just add the following service to your pup.jsonc file:
You can find more information about pup on their documentation page.
The NATS server configuration is done via environment variables. The following table lists all available environment variables and their default values.
+| Environment Variable | +Default Value | +Description | +
|---|---|---|
NATS_HOST |
+localhost |
+The host of the NATS server. | +
NATS_PORT |
+4222 |
+The port of the NATS server. | +
@wuespace/telestion / auth / LoginError
+auth.LoginError
+Error↳ LoginError
• new LoginError(messages): LoginError
| Name | +Type | +
|---|---|
messages |
+ErrorMessages |
+
Error.constructor
+• message: string
Error.message
+• messages: ErrorMessages
• name: string
Error.name
+• Optional stack: string
Error.stack
+▪ Static Optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any
▸ (err, stackTraces): any
Optional override for formatting stack traces
+| Name | +Type | +
|---|---|
err |
+Error |
+
stackTraces |
+CallSite[] |
+
any
See
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+Error.prepareStackTrace
+▪ Static stackTraceLimit: number
Error.stackTraceLimit
+▸ captureStackTrace(targetObject, constructorOpt?): void
Create .stack property on a target object
+| Name | +Type | +
|---|---|
targetObject |
+object |
+
constructorOpt? |
+Function |
+
void
Error.captureStackTrace
+ + + + + + + + + + + + + +@wuespace/telestion
+The Telestion Frontend Library.
+Import this library to use the Telestion Frontend:
+ +The most important function is initTelestion. +It initializes the Telestion Frontend and renders the application.
+ +See
Re-exports TelestionOptions
+Re-exports UserData
+Re-exports Widget
+Re-exports initTelestion
+Re-exports registerWidgets
+Re-exports useNats
+Re-exports useWidgetConfig
+ + + + + + + + + + + + + +@wuespace/telestion / application / TelestionOptions
+application.TelestionOptions
+Represents the options for Telestion.
+• Optional defaultBackendUrl: string
The backend URL that should be inserted by default on first page load.
+• Optional defaultUserData: Object
Represents the default user data.
+| Name | +Type | +Description | +
|---|---|---|
dashboards |
+Record<string, { title: string; layout: string[][]; }> |
+The user’s dashboards. | +
version |
+string |
+The version of the client that created this user data. | +
widgetInstances |
+Record<string, { type: string; configuration: Record<string, unknown>; }> |
+The user’s widget instances. | +
• version: string
Represents the current version of the software.
+• Optional widgets: Widget<Record<string, unknown>>[]
Represents an array of widgets.
+ + + + + + + + + + + + + +@wuespace/telestion / auth / ErrorMessages
+auth.ErrorMessages
+• Optional natsUrlMessage: string
• Optional passwordMessage: string
• Optional usernameMessage: string
@wuespace/telestion / widget / Widget
+widget.Widget
+A widget that can be used in widget instances on dashboards.
+See
| Name | +Type | +Description | +
|---|---|---|
T |
+extends Record<string, unknown> = Record<string, unknown> |
+the type of the widget configuration | +
• configElement: ReactNode
A configuration element that is used to configure the widget.
+• element: ReactNode
A function that takes the configuration of the widget and returns a React element that represents the widget.
+• id: string
Represents an identifier of the widget type.
+• label: string
Represents a human-readable label of the widget type.
+▸ createConfig(input): T
A function that takes an object that contains the previous widget configuration (which may or may not be from a +previous version of the client (or could also, when creating new widget instances, be empty) and returns a valid +configuration for the widget.
+For widgets with expected breaking changes, it is therefore useful to have some version identifier be a part +of the configuration options to enable more complex migration logic in this function.
+| Name | +Type | +Description | +
|---|---|---|
input |
+Partial<T> & Record<string, unknown> |
+previous configuration or empty | +
T
@wuespace/telestion / application
+▸ initTelestion(options): Promise<void>
Initialize the Telestion application.
+| Name | +Type | +Description | +
|---|---|---|
options |
+TelestionOptions |
+The options for initializing the application. | +
Promise<void>
A Promise that resolves once the initialization is completed.
+▸ useWidgetConfig<T>(): T
Retrieves the widget configuration from the widgetConfigContext.
+| Name | +Description | +
|---|---|
T |
+The type of the widget configuration. | +
T
The widget configuration retrieved from the widgetConfigContext.
+Throws
Error Throws an error if useWidgetConfig is not used within a WidgetConfigProvider.
+ + + + + + + + + + + + + +@wuespace/telestion / auth
+▸ getNatsConnection(): null | NatsConnection
null | NatsConnection
▸ getUser(): null | User
Returns the user object if the user is currently logged in, else returns null if no user is currently logged in.
null | User
▸ isLoggedIn(): boolean
Checks if a user is logged in.
+boolean
true if the user is logged in, false otherwise.
▸ login(natsUrl, username, password): Promise<null | User>
Logs in a user with the given credentials.
+| Name | +Type | +Description | +
|---|---|---|
natsUrl |
+string |
+The url to connect to the NATS server. | +
username |
+string |
+The username for authentication. | +
password |
+string |
+The password for authentication. | +
A promise that resolves once the user is logged in. +The resolved value is the logged-in user object.
+Throws
Error If the provided credentials are incorrect.
+▸ logout(): Promise<void>
Logs out the user if currently logged in.
+Promise<void>
A promise that resolves once the user is logged out.
+▸ setNatsConnection(nc): void
| Name | +Type | +
|---|---|
nc |
+null | NatsConnection |
+
void
▸ setUser(user): void
Sets a new user object or null if the user is no longer logged in.
| Name | +Type | +Description | +
|---|---|---|
user |
+null | User |
+the user object or null |
+
void
▸ useNats(): NatsConnection
NatsConnection
▸ useNatsSubscription(subject, callback, options?): void
| Name | +Type | +
|---|---|
subject |
+string |
+
callback |
+(message: Msg) => void | Promise<void> |
+
options? |
+SubscriptionOptions |
+
void
@wuespace/telestion / userData
+Ƭ Dashboard: Object
Represents a dashboard.
+See
| Name | +Type | +Description | +
|---|---|---|
layout |
+string[][] |
+The layout of the dashboard. | +
title |
+string |
+The title of the dashboard. | +
Ƭ UserData: Object
Represents the user data.
+See
| Name | +Type | +Description | +
|---|---|---|
dashboards |
+Record<string, { title: string; layout: string[][]; }> |
+The user’s dashboards. | +
version |
+string |
+The version of the client that created this user data. | +
widgetInstances |
+Record<string, { type: string; configuration: Record<string, unknown>; }> |
+The user’s widget instances. | +
Ƭ WidgetInstance: Object
Represents a widget instance.
+See
| Name | +Type | +Description | +
|---|---|---|
configuration |
+Record<string, unknown> |
+The configuration of the widget. | +
type |
+string |
+The type ID of the widget. This is used to determine which widget type to use to render the widget. See Widget.id |
+
• Const dashboardSchema: ZodObject<Dashboard>
Represents the schema for a dashboard.
+• Const idSchema: ZodString
A regular expression that matches valid identifiers.
+Used for dashboard and widget instance IDs.
+See
• Const layoutSchema: ZodArray<ZodArray<ZodUnion<[ZodString, ZodLiteral<".">]>, "many">, "many">
A schema that matches valid layout configurations.
+• Const semverRegExp: RegExp
A regular expression that matches semantic version numbers.
+Taken from https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string
+• Const userDataSchema: ZodObject<UserData>
The schema for the user data.
+See
• Const widgetInstanceSchema: ZodObject<WidgetInstance>
Represents the schema for a widget instance.
+See
▸ getBlankUserData(version): UserData
Returns a new blank user data object.
+| Name | +Type | +Description | +
|---|---|---|
version |
+string |
+the current application version | +
▸ getEmptyDashboard(): readonly [id: string, dashboard: Dashboard]
+Returns a new and empty dashboard with a unique id.
+readonly [id: string, dashboard: Dashboard]
+▸ getUserData(): undefined | { dashboards: Record<string, { title: string; layout: string[][]; }> ; version: string ; widgetInstances: Record<string, { type: string; configuration: Record<string, unknown>; }> }
Retrieves user data from local storage.
+undefined | { dashboards: Record<string, { title: string; layout: string[][]; }> ; version: string ; widgetInstances: Record<string, { type: string; configuration: Record<string, unknown>; }> }
The user data if found in local storage, otherwise undefined.
+▸ removeUserData(): void
Removes the user data from local storage.
+void
▸ setUserData(newUserData): void
Sets the user data in the local storage based on the given input.
+| Name | +Type | +Description | +
|---|---|---|
newUserData |
+Object |
+The new user data to be set. | +
newUserData.dashboards |
+Record<string, { title: string; layout: string[][]; }> |
+The user’s dashboards. | +
newUserData.version |
+string |
+The version of the client that created this user data. | +
newUserData.widgetInstances |
+Record<string, { type: string; configuration: Record<string, unknown>; }> |
+The user’s widget instances. | +
void
@wuespace/telestion / utils
+▸ generateDashboardId(): string
Generates a unique identifier for a dashboard.
+string
The generated dashboard identifier.
+▸ isUserDataUpToDate(userData, currentVersion): boolean
Checks if the user data is up-to-date with the current version of the application.
+| Name | +Type | +Description | +
|---|---|---|
userData |
+undefined | { dashboards: Record<string, { title: string; layout: string[][]; }> ; version: string ; widgetInstances: Record<string, { type: string; configuration: Record<string, unknown>; }> } |
+the user data to compare with the application version | +
currentVersion |
+string |
+the current version of the application | +
boolean
▸ loadFileContents(file, encoding?): Promise<string>
Loads the contents of a specified file.
+| Name | +Type | +Default value | +Description | +
|---|---|---|---|
file |
+File |
+undefined |
+The file object to load contents from. | +
encoding |
+string |
+'utf-8' |
+The encoding to use while reading the file. Default is UTF-8. | +
Promise<string>
▸ wait(timeout): Promise<void>
Waits for the specified amount of time before resolving the returned promise.
+| Name | +Type | +Description | +
|---|---|---|
timeout |
+number |
+The duration in milliseconds to wait before resolving. | +
Promise<void>
A promise that resolves after the specified time has elapsed.
+ + + + + + + + + + + + + +@wuespace/telestion / widget
+• Const widgetConfigContext: Context<unknown>
▸ WidgetRenderer(WidgetRendererProps): Element
Renders a widget based on the provided widgetInstanceId.
+| Name | +Type | +Description | +
|---|---|---|
WidgetRendererProps |
+WidgetRendererProps |
+The props for the WidgetRenderer. | +
Element
The rendered widget.
+Throws
Error If the widget instance is not found.
+▸ getWidgetById(id): undefined | Widget<Record<string, unknown>>
Retrieves a widget by its unique type ID.
+| Name | +Type | +Description | +
|---|---|---|
id |
+string |
+The unique type ID of the widget. | +
undefined | Widget<Record<string, unknown>>
The widget associated with the ID, or null if the widget is not found.
+▸ getWidgets(): Widget<Record<string, unknown>>[]
Returns an array of all the widgets that are currently registered.
+Widget<Record<string, unknown>>[]
An array containing all the widgets.
+▸ registerWidgets(...widgets): void
Registers widgets in the widget store.
+If a widget with the same ID already exists in the widget store, a warning is logged and the widget is ignored.
+| Name | +Type | +Description | +
|---|---|---|
...widgets |
+Widget<Record<string, unknown>>[] |
+The widgets to be registered. | +
void
This document describes the various concepts you need to know when building components for the Telestion frontend.
+The Telestion frontend is the part of Telestion that is visible to the user. It is built with React and TypeScript. It is responsible for displaying data from the backend and for sending commands to the backend.
+HTML, CSS, and JavaScript are the three core technologies of the web. HTML is used to describe the structure of web pages. CSS is used to describe the presentation of web pages. JavaScript is used to describe the behavior of web pages.
+The Telestion frontend is built with React. React is a JavaScript library for building user interfaces. It is component-based and declarative. This means that you can build your UI from small, reusable components and that you can describe how your UI should look like without having to worry about how it is rendered.
+Components are the building blocks of React applications. They are small, reusable pieces of code that can be composed to build more complex components. Components can be either functional or class-based. Functional components are just functions that return a React element.
+JSX is a syntax extension to JavaScript that allows you to write HTML-like code in your JavaScript files. It is not required to use JSX when writing React applications, but it is recommended. JSX makes your code more readable and easier to write. It also allows you to use the full power of JavaScript inside your HTML-like code.
+Props are the way to pass data from a parent component to a child component. They are immutable and can only be changed by the parent component. Props are passed to a component as attributes in JSX.
+State is the way to store data inside a component. It is mutable and can be changed by the component itself.
+You can initialize and use state using the useState() hook like this:
const [counter, setCounter] = useCounter(0); // initialize with 0
+setCounter(counter + 1); // increase counter by 1
+Hooks are a new feature that was introduced in React 16.8. They allow you to use state and other React features without writing a class. Hooks are functions that can be called inside functional components. They allow you to use state and other React features without writing a class.
+The Telestion frontend is written in TypeScript. TypeScript is a superset of JavaScript that adds static typing to the language. It is a strict superset of JavaScript, which means that any valid JavaScript code is also valid TypeScript code. TypeScript is a statically typed language, which means that the type of a variable is known at compile time. This allows the compiler to catch many errors at compile time instead of at runtime.
+ + + + + + + + + + + + + + + + +Processing data is only half the fun. To make the data accessible to the user, you need a frontend.
+Telestion uses a frontend based on React, TypeScript, and Bootstrap. +Thankfully, Telestion (together with vite) provides a lot of tools to make frontend development as easy as possible.
+All you need to get started is an installation of Node.js and pnpm.
+To create a new frontend, create a new directory for it:
+ +Now, add the following files to your directory:
+package.json¶{
+ "name": "telestion-frontend",
+ "version": "1.0.0",
+ "type": "module",
+ "dependencies": {
+ "@wuespace/telestion": "^1.0.0-alpha.2",// (1)!
+ "react": "^18.2.0",
+ "zod": "^3.22.4"// (2)!
+ },
+ "devDependencies": {
+ "@vitejs/plugin-react-swc": "^4.2.1",
+ "vite": "^5.0.8"
+ }
+}
+@wuespace/telestion package as a dependency. This package contains all the tools you need to get started with frontend development.zod package as a dependency. This package is used to validate any data that is sent to the frontend.vite.config.ts¶import { defineConfig } from "vite";
+import react from '@vitejs/plugin-react-swc';
+
+export default defineConfig({
+ plugins: [react()/*(1)!*/],
+});
+react plugin to vite. This plugin allows you to use React in your frontend.index.html¶<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Telestion Frontend</title>
+ </head>
+ <body data-bs-theme="dark"><!-- (1)! -->
+ <div id="root"></div><!-- (2)! -->
+ <script type="module" src="/index.ts"></script><!-- (3)! -->
+ </body>
+</html>
+data-bs-theme attribute to the body tag. This attribute is used to set the default theme of the frontend. You can choose between light and dark.div tag with the id root. This is where your frontend will be rendered.script tag that loads the index.ts file. This file is the entry point of your frontend.index.ts¶import { initTelestion, registerWidgets } from "@wuespace/telestion"; // (1)!
+
+import "@wuespace/telestion/telestion.css"; // (2)!
+
+// initialize Telestion
+await initTelestion/* (3)!*/({
+ version: "1.0.0",// (4)!
+});
+
+// register your widget in Telestion
+registerWidgets(...);// (5)!
+initTelestion and registerWidgets functions from the @wuespace/telestion package.telestion.css file from the @wuespace/telestion package. This file contains all the styles (including all Bootstrap styles) you need to get started with frontend development.To install the dependencies, run the following command:
+ +To run the frontend, run the following command:
+ +This will start a development server on port 5173. You can now open your browser and navigate to +http://localhost:5173.
+To build the frontend, run the following command:
+ +Now that you have a basic frontend running, you should have a look at how to add widgets to it.
+ + + + + + + + + + + + + +${p.children.map(f).join("")}
`:`Unsupported markdown: ${p.type}`}return a.map(f).join("")}function b$e(i){return Intl.Segmenter?[...new Intl.Segmenter().segment(i)].map(a=>a.segment):[...i]}function w$e(i,a){const f=b$e(a.content);return uBt(i,[],f,a.type)}function uBt(i,a,f,p){if(f.length===0)return[{content:a.join(""),type:p},{content:"",type:p}];const[w,...m]=f,b=[...a,w];return i([{content:b.join(""),type:p}])?uBt(i,b,m,p):(a.length===0&&w&&(a.push(w),f.shift()),[{content:a.join(""),type:p},{content:f.join(""),type:p}])}function v$e(i,a){if(i.some(({content:f})=>f.includes(` +`)))throw new Error("splitLineToFitWidth does not support newlines in the line");return O0t(i,a)}function O0t(i,a,f=[],p=[]){if(i.length===0)return p.length>0&&f.push(p),f.length>0?f:[];let w="";i[0].content===" "&&(w=" ",i.shift());const m=i.shift()??{content:" ",type:"normal"},b=[...p];if(w!==""&&b.push({content:w,type:"normal"}),b.push(m),a(b))return O0t(i,a,f,b);if(p.length>0)f.push(p),i.unshift(m);else if(m.content){const[E,_]=w$e(a,m);f.push([E]),_.content&&i.unshift(_)}return O0t(i,a,f)}function m$e(i,a){a&&i.attr("style",a)}function y$e(i,a,f,p,w=!1){const m=i.append("foreignObject"),b=m.append("xhtml:div"),E=a.label,_=a.isNode?"nodeLabel":"edgeLabel";b.html(` + "+E+""),m$e(b,a.labelStyle),b.style("display","table-cell"),b.style("white-space","nowrap"),b.style("max-width",f+"px"),b.attr("xmlns","http://www.w3.org/1999/xhtml"),w&&b.attr("class","labelBkg");let A=b.node().getBoundingClientRect();return A.width===f&&(b.style("display","table"),b.style("white-space","break-spaces"),b.style("width",f+"px"),A=b.node().getBoundingClientRect()),m.style("width",A.width),m.style("height",A.height),m.node()}function P0t(i,a,f){return i.append("tspan").attr("class","text-outer-tspan").attr("x",0).attr("y",a*f-.1+"em").attr("dy",f+"em")}function x$e(i,a,f){const p=i.append("text"),w=P0t(p,1,a);F0t(w,f);const m=w.node().getComputedTextLength();return p.remove(),m}function k$e(i,a,f){var b;const p=i.append("text"),w=P0t(p,1,a);F0t(w,[{content:f,type:"normal"}]);const m=(b=w.node())==null?void 0:b.getBoundingClientRect();return m&&p.remove(),m}function E$e(i,a,f,p=!1){const m=a.append("g"),b=m.insert("rect").attr("class","background"),E=m.append("text").attr("y","-10.1");let _=0;for(const A of f){const I=N=>x$e(m,1.1,N)<=i,B=I(A)?[A]:v$e(A,I);for(const N of B){const R=P0t(E,_,1.1);F0t(R,N),_++}}if(p){const A=E.node().getBBox(),I=2;return b.attr("x",-I).attr("y",-I).attr("width",A.width+2*I).attr("height",A.height+2*I),m.node()}else return E.node()}function F0t(i,a){i.text(""),a.forEach((f,p)=>{const w=i.append("tspan").attr("font-style",f.type==="emphasis"?"italic":"normal").attr("class","text-inner-tspan").attr("font-weight",f.type==="strong"?"bold":"normal");p===0?w.text(f.content):w.text(" "+f.content)})}const EY=(i,a="",{style:f="",isTitle:p=!1,classes:w="",useHtmlLabels:m=!0,isNode:b=!0,width:E=200,addSvgBackground:_=!1}={})=>{if(Ut.info("createText",a,f,p,w,m,b,_),m){const A=p$e(a),I={isNode:b,label:uF(A).replace(/fa[blrs]?:fa-[\w-]+/g,N=>``),labelStyle:f.replace("fill:","color:")};return y$e(i,I,E,w,_)}else{const A=g$e(a);return E$e(E,i,A,_)}},Nd=async(i,a,f,p)=>{let w;const m=a.useHtmlLabels||o1(Oe().flowchart.htmlLabels);f?w=f:w="node default";const b=i.insert("g").attr("class",w).attr("id",a.domId||a.id),E=b.insert("g").attr("class","label").attr("style",a.labelStyle);let _;a.labelText===void 0?_="":_=typeof a.labelText=="string"?a.labelText:a.labelText[0];const A=E.node();let I;a.labelType==="markdown"?I=EY(E,Q1(uF(_),Oe()),{useHtmlLabels:m,width:a.width||Oe().flowchart.wrappingWidth,classes:"markdown-node-label"}):I=A.appendChild(gp(Q1(uF(_),Oe()),a.labelStyle,!1,p));let B=I.getBBox();const N=a.padding/2;if(o1(Oe().flowchart.htmlLabels)){const R=I.children[0],z=yr(I),W=R.getElementsByTagName("img");if(W){const et=_.replace(/