SDKs · TypeScript

Connect to the runtime

Dial a Phrony runtime with RuntimeClient, Phrony, or low-level helpers.

Every SDK entrypoint dials the runtime over gRPC. Set PHRONY_RUNTIME_ADDR or pass an explicit address. After installing the package, use one of the patterns below.

RuntimeClient

RuntimeClient.connect(options?)

Dial the runtime and health service. Options: address, credentials, clientOptions. The resolved address is available on client.address.

TypeScript

import { RuntimeClient } from "@phrony/sdk";

const client = await RuntimeClient.connect({
  address: process.env.PHRONY_RUNTIME_ADDR ?? "127.0.0.1:7777",
});

console.log("Connected to", client.address);

client.close()

Close runtime and health gRPC clients when finished.

TypeScript

const client = await RuntimeClient.connect();
// ...
client.close();

Phrony

Phrony.connect(options?)

High-level facade with the same connection options (runtimeAddr maps to address).

TypeScript

import { Phrony } from "@phrony/sdk";

const phrony = await Phrony.connect({
  runtimeAddr: process.env.PHRONY_RUNTIME_ADDR,
});

// Same options as RuntimeClient: credentials, address via runtimeAddr
phrony.close();

Address resolution

resolveRuntimeAddr(address?)

Resolve the gRPC target: explicit argument, then PHRONY_RUNTIME_ADDR, then 127.0.0.1:7777.

TypeScript

import { resolveRuntimeAddr, DEFAULT_RUNTIME_ADDR } from "@phrony/sdk";

// Explicit address wins, then PHRONY_RUNTIME_ADDR, then DEFAULT_RUNTIME_ADDR
const addr = resolveRuntimeAddr(); // e.g. "127.0.0.1:7777"
console.log(DEFAULT_RUNTIME_ADDR);

dialRuntime(options?)

Low-level dial returning runtime, health, address, and close() without the RuntimeClient wrapper.

TypeScript

import { dialRuntime } from "@phrony/sdk";

const dial = dialRuntime({ address: "127.0.0.1:7777" });
try {
  const version = await new Promise((resolve, reject) => {
    dial.runtime.getVersion({}, (err, res) => (err ? reject(err) : resolve(res)));
  });
  console.log(version);
} finally {
  dial.close();
}

TLS

credentials (optional)

By default the SDK uses insecure credentials. Pass createSsl from @grpc/grpc-js when the runtime requires TLS.

TypeScript

import { credentials } from "@grpc/grpc-js";
import { readFileSync } from "node:fs";
import { RuntimeClient } from "@phrony/sdk";

const client = await RuntimeClient.connect({
  address: "runtime.example.com:7777",
  credentials: credentials.createSsl(
    readFileSync("ca.pem"),
    readFileSync("client-key.pem"),
    readFileSync("client-cert.pem"),
  ),
});

Health check

client.health()

Standard gRPC health client on the same address as the runtime.

TypeScript

import { RuntimeClient } from "@phrony/sdk";

const client = await RuntimeClient.connect();
const health = client.health();

await new Promise<void>((resolve, reject) => {
  health.check({ service: "" }, (err, res) => {
    if (err) reject(err);
    else {
      console.log(res?.status); // SERVING, NOT_SERVING, etc.
      resolve();
    }
  });
});

client.close();

Cleanup

Phrony.close() / RuntimeClient.close()

TypeScript

import { Phrony, RuntimeClient } from "@phrony/sdk";

const client = await RuntimeClient.connect();
client.close();

const phrony = await Phrony.connect();
phrony.close();