@synnaxlabs/client 0.1.2 → 0.2.0

package/src/lib/channel/retriever.ts

@@ -0,0 +1,53 @@
+import { UnaryClient } from '@synnaxlabs/freighter';
+import { z } from 'zod';
+
+import Transport from '../transport';
+
+import { ChannelPayload, ChannelPayloadSchema } from './payload';
+
+const RequestSchema = z.object({
+  keys: z.string().array().optional(),
+  nodeId: z.number().optional(),
+  names: z.string().array().optional(),
+});
+
+type Request = z.infer<typeof RequestSchema>;
+
+const ResponseSchema = z.object({
+  channels: ChannelPayloadSchema.array(),
+});
+
+export default class Retriever {
+  private static ENDPOINT = '/channel/retrieve';
+  private client: UnaryClient;
+
+  constructor(transport: Transport) {
+    this.client = transport.getClient();
+  }
+
+  private async execute(request: Request): Promise<ChannelPayload[]> {
+    const [res, err] = await this.client.send(
+      Retriever.ENDPOINT,
+      request,
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      ResponseSchema
+    );
+    if (err) {
+      throw err;
+    }
+    return res?.channels as ChannelPayload[];
+  }
+
+  async retrieveByKeys(...keys: string[]): Promise<ChannelPayload[]> {
+    return await this.execute({ keys });
+  }
+
+  async retrieveByNames(...names: string[]): Promise<ChannelPayload[]> {
+    return await this.execute({ names });
+  }
+
+  async retrieveByNodeID(nodeId: number): Promise<ChannelPayload[]> {
+    return await this.execute({ nodeId: nodeId });
+  }
+}

package/src/lib/client.ts

@@ -0,0 +1,53 @@
+import { URL } from '@synnaxlabs/freighter';
+
+import AuthenticationClient from './auth';
+import ChannelClient from './channel/client';
+import ChannelCreator from './channel/creator';
+import Registry from './channel/registry';
+import ChannelRetriever from './channel/retriever';
+import SegmentClient from './segment/client';
+import Transport from './transport';
+
+export type SynnaxProps = {
+  host: string;
+  port: number;
+  username?: string;
+  password?: string;
+};
+
+/**
+ * Client to perform operations against a Synnax cluster.
+ *
+ * @property channel - Channel client for creating and retrieving channels.
+ * @property data - Data client for reading and writing telemetry.
+ */
+export default class Synnax {
+  private transport: Transport;
+  data: SegmentClient;
+  channel: ChannelClient;
+  auth: AuthenticationClient | undefined;
+
+  /**
+   * @param props.host - Hostname of a node in the cluster.
+   * @param props.port - Port of the node in the cluster.
+   * @param props.username - Username for authentication. Not required if the
+   *   cluster is insecure.
+   * @param props.password - Password for authentication. Not required if the
+   *   cluster is insecure.
+   */
+  constructor({ host, port, username, password }: SynnaxProps) {
+    this.transport = new Transport(new URL({ host, port }));
+    if (username && password) {
+      this.auth = new AuthenticationClient(this.transport.httpFactory, {
+        username,
+        password,
+      });
+      this.transport.use(this.auth.middleware());
+    }
+    const chRetriever = new ChannelRetriever(this.transport);
+    const chCreator = new ChannelCreator(this.transport);
+    const chRegistry = new Registry(chRetriever);
+    this.data = new SegmentClient(this.transport, chRegistry);
+    this.channel = new ChannelClient(this.data, chRetriever, chCreator);
+  }
+}

package/src/lib/errors.ts

@@ -0,0 +1,133 @@
+import { BaseTypedError, registerError } from '@synnaxlabs/freighter';
+import { z } from 'zod';
+
+const _FREIGHTER_EXCEPTION_TYPE = 'synnax.api.errors';
+
+const APIErrorPayloadSchema = z.object({
+  type: z.string(),
+  error: z.record(z.unknown()),
+});
+
+type APIErrorPayload = z.infer<typeof APIErrorPayloadSchema>;
+
+enum APIErrorType {
+  General = 'general',
+  Nil = 'nil',
+  Parse = 'parse',
+  Auth = 'auth',
+  Unexpected = 'unexpected',
+  Validation = 'validation',
+  Query = 'query',
+  Route = 'route',
+}
+
+export type Field = {
+  field: string;
+  message: string;
+};
+
+class BaseError extends BaseTypedError {
+  constructor(message: string) {
+    super(message, _FREIGHTER_EXCEPTION_TYPE);
+  }
+}
+
+/**
+ * Raised when a validation error occurs.
+ */
+export class ValidationError extends BaseError {
+  fields: Field[];
+
+  constructor(fieldsOrMessage: string | Field[] | Field) {
+    if (typeof fieldsOrMessage === 'string') {
+      super(fieldsOrMessage);
+      this.fields = [];
+    } else if (Array.isArray(fieldsOrMessage)) {
+      super(
+        fieldsOrMessage
+          .map((field) => `${field.field}: ${field.message}`)
+          .join('\n')
+      );
+      this.fields = fieldsOrMessage;
+    } else {
+      super(`${fieldsOrMessage.field}: ${fieldsOrMessage.message}`);
+      this.fields = [fieldsOrMessage];
+    }
+  }
+}
+
+/**
+ * GeneralError is raised when a general error occurs.
+ */
+export class GeneralError extends BaseError {}
+
+/**
+ * ParseError is raised when a parse error occurs.
+ */
+export class ParseError extends BaseError {}
+
+/**
+ * AuthError is raised when an authentication error occurs.
+ */
+export class AuthError extends BaseError {}
+
+/**
+ * UnexpectedError is raised when an unexpected error occurs.
+ */
+export class UnexpectedError extends BaseError {}
+
+/**
+ * QueryError is raised when a query error occurs.
+ */
+export class QueryError extends BaseError {}
+
+/**
+ * RouteError is raised when a routing error occurs.
+ */
+export class RouteError extends BaseError {
+  path: string;
+
+  constructor(message: string, path: string) {
+    super(message);
+    this.path = path;
+  }
+}
+
+/**
+ * Raised when time-series data is not contiguous.
+ */
+export class ContiguityError extends BaseError {}
+
+const parsePayload = (payload: APIErrorPayload): Error | undefined => {
+  switch (payload.type) {
+    case APIErrorType.General:
+      return new GeneralError(payload.error.message as string);
+    case APIErrorType.Parse:
+      return new ParseError(payload.error.message as string);
+    case APIErrorType.Auth:
+      return new AuthError(payload.error.message as string);
+    case APIErrorType.Unexpected:
+      return new UnexpectedError(JSON.stringify(payload.error));
+    case APIErrorType.Validation:
+      return new ValidationError(payload.error.fields as string | Field[]);
+    case APIErrorType.Query:
+      return new QueryError(payload.error.message as string);
+    case APIErrorType.Route:
+      return new RouteError(
+        payload.error.path as string,
+        payload.error.message as string
+      );
+    default:
+      return undefined;
+  }
+};
+
+const decode = (encoded: string): Error | undefined => {
+  return parsePayload(APIErrorPayloadSchema.parse(JSON.parse(encoded)));
+};
+
+const encode = (): string => {
+  throw new Error('Not implemented');
+};
+
+registerError({ type: _FREIGHTER_EXCEPTION_TYPE, encode, decode });

package/src/lib/segment/client.ts

@@ -0,0 +1,126 @@
+import Registry from '../channel/registry';
+import { TimeRange, TypedArray, UnparsedTimeStamp } from '../telem';
+import Transport from '../transport';
+
+import { TypedIterator } from './iterator';
+import TypedSegment from './typed';
+import { TypedWriter } from './writer';
+
+export default class SegmentClient {
+  private transport: Transport;
+  private channels: Registry;
+
+  constructor(transport: Transport, channels: Registry) {
+    this.transport = transport;
+    this.channels = channels;
+  }
+
+  /**
+   * Opens a new iterator over the given channels within the provided time range.
+   *
+   * @param tr - A time range to iterate over.
+   * @param keys - A list of channel keys to iterate over.
+   * @param aggregate - Whether to accumulate iteration results or reset them
+   * on every iterator method call.
+   * @returns a new {@link TypedIterator}.
+   */
+  async newIterator(
+    tr: TimeRange,
+    keys: string[],
+    aggregate: boolean
+  ): Promise<TypedIterator> {
+    const iter = new TypedIterator(
+      this.transport.streamClient,
+      this.channels,
+      aggregate
+    );
+    await iter.open(tr, keys);
+    return iter;
+  }
+
+  /**
+   * Opens a new writer on the given channels.
+   *
+   * @param keys - The keys of the channels to write to. A writer cannot write to
+   * a channel that is not in this list. See the {@link TypedWriter} documentation
+   * for more information.
+   * @returns a new {@link TypedWriter}.
+   */
+  async newWriter(keys: string[]): Promise<TypedWriter> {
+    const writer = new TypedWriter(this.transport.streamClient, this.channels);
+    await writer.open(keys);
+    return writer;
+  }
+
+  /**
+   * Writes telemetry to the given channel starting at the given timestamp.
+   *
+   * @param to - The key of the channel to write to.
+   * @param start - The starting timestamp of the first sample in data.
+   * @param data  - The telemetry to write. This telemetry must have the same
+   * data type as the channel.
+   * @throws if the channel does not exist.
+   */
+  async write(
+    to: string,
+    start: UnparsedTimeStamp,
+    data: TypedArray
+  ): Promise<boolean> {
+    const writer = await this.newWriter([to]);
+    try {
+      return await writer.write(to, start, data);
+    } finally {
+      await writer.close();
+    }
+  }
+
+  /**
+   * Reads telemetry from the channel between the two timestamps.
+   *
+   * @param from - The key of the channel to read from.
+   * @param start - The starting timestamp of the range to read from.
+   * @param end - The ending timestamp of the range to read from.
+   * @returns a typed array containing the retrieved telemetry.
+   * @throws if the channel does not exist.
+   * @throws if the telemetry between start and end is not contiguous.
+   */
+  async read(
+    from: string,
+    start: UnparsedTimeStamp,
+    end: UnparsedTimeStamp
+  ): Promise<TypedArray> {
+    return (await this.readSegment(from, start, end)).view;
+  }
+
+  /**
+   * Reads a segment from the channel between the two timestamps.
+   *
+   * @param from - The key of the channel to read from.
+   * @param start - The starting timestamp of the range to read from.
+   * @param end - The ending timestamp of the range to read from.
+   * @returns a segment containing the retrieved telemetry.
+   * @throws if the channel does not exist.
+   * @throws if the telemetry between start and end is not contiguous.
+   */
+  async readSegment(
+    from: string,
+    start: UnparsedTimeStamp,
+    end: UnparsedTimeStamp
+  ): Promise<TypedSegment> {
+    const iter = await this.newIterator(
+      new TimeRange(start, end),
+      [from],
+      true
+    );
+    let seg: TypedSegment;
+    try {
+      await iter.first();
+      // eslint-disable-next-line no-empty
+      while (await iter.next()) {}
+      seg = (await iter.value())[from];
+    } finally {
+      await iter.close();
+    }
+    return seg as TypedSegment;
+  }
+}

package/src/lib/segment/iterator.spec.ts

@@ -0,0 +1,78 @@
+import test from 'ava';
+
+import { newClient } from '../../setupspecs';
+import { ContiguityError } from '../errors';
+import { DataType, Rate, TimeRange, TimeSpan } from '../telem';
+import { randomTypedArray } from '../util/telem';
+
+const client = newClient();
+
+const newChannel = async () => {
+  return await client.channel.create({
+    name: 'test',
+    nodeId: 1,
+    rate: Rate.Hz(25),
+    dataType: DataType.Float64,
+  });
+};
+
+test('TypedIterator - basic iteration', async (t) => {
+  const ch = await newChannel();
+  const writer = await client.data.newWriter([ch.key]);
+  const data = randomTypedArray(25, ch.dataType);
+  try {
+    await writer.write(ch.key, TimeSpan.Second, data);
+    await writer.write(ch.key, TimeSpan.Seconds(2), data);
+    await writer.write(ch.key, TimeSpan.Seconds(3), data);
+  } finally {
+    await writer.close();
+  }
+  const iterator = await client.data.newIterator(
+    new TimeRange(TimeSpan.Zero, TimeSpan.Seconds(4)),
+    [ch.key],
+    false
+  );
+  try {
+    t.true(await iterator.first());
+    t.true((await iterator.value())[ch.key].view.length === 25);
+    let c = 1;
+    while (await iterator.next()) {
+      c++;
+      t.true((await iterator.value())[ch.key].view.length === 25);
+    }
+    t.true(c === 3);
+  } finally {
+    await iterator.close();
+  }
+});
+
+test('Client - basic read', async (t) => {
+  const ch = await newChannel();
+  const writer = await client.data.newWriter([ch.key]);
+  const data = randomTypedArray(25, ch.dataType);
+  try {
+    await writer.write(ch.key, TimeSpan.Second, data);
+    await writer.write(ch.key, TimeSpan.Seconds(2), data);
+    await writer.write(ch.key, TimeSpan.Seconds(3), data);
+  } finally {
+    await writer.close();
+  }
+  const resData = await client.data.read(
+    ch.key,
+    TimeSpan.Zero,
+    TimeSpan.Seconds(4)
+  );
+  resData.slice(0, 25).forEach((v, i) => t.true(v === data[i]));
+  t.true(resData.length === 75);
+});
+
+test('Client - incontiguous read', async (t) => {
+  const ch = await newChannel();
+  const data = randomTypedArray(25, ch.dataType);
+  await ch.write(TimeSpan.Zero, data);
+  await ch.write(TimeSpan.Seconds(2), data);
+  const err = await t.throwsAsync(async () => {
+    await client.data.read(ch.key, TimeSpan.Zero, TimeSpan.Seconds(4));
+  });
+  t.true(err instanceof ContiguityError);
+});