@synnaxlabs/client 0.2.0 → 0.2.1

package/src/lib/client.ts

@@ -1,53 +0,0 @@
-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

@@ -1,133 +0,0 @@
-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

@@ -1,126 +0,0 @@
-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

@@ -1,78 +0,0 @@
-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);
-});

package/src/lib/segment/iterator.ts

@@ -1,281 +0,0 @@
-import {
-  EOF,
-  ErrorPayloadSchema,
-  Stream,
-  StreamClient,
-} from '@synnaxlabs/freighter';
-import { z } from 'zod';
-
-import { ChannelPayload } from '../channel/payload';
-import Registry from '../channel/registry';
-import { TimeRange } from '../telem';
-
-import { SegmentPayload, SegmentPayloadSchema } from './payload';
-import TypedSegment from './typed';
-
-enum Command {
-  Open = 0,
-  Next = 1,
-  Prev = 2,
-  First = 3,
-  Last = 4,
-  NextSpan = 5,
-  PrevSpan = 6,
-  NextRange = 7,
-  Valid = 8,
-  Error = 9,
-  SeekFirst = 10,
-  SeekLast = 11,
-  SeekLT = 12,
-  SeekGE = 13,
-}
-
-enum ResponseVariant {
-  None = 0,
-  Ack = 1,
-  Data = 2,
-}
-
-const RequestSchema = z.object({
-  command: z.nativeEnum(Command),
-  span: z.number().optional(),
-  range: z.instanceof(TimeRange).optional(),
-  stamp: z.number().optional(),
-  keys: z.string().array().optional(),
-});
-
-type Request = z.infer<typeof RequestSchema>;
-
-const ResponseSchema = z.object({
-  variant: z.nativeEnum(ResponseVariant),
-  ack: z.boolean(),
-  command: z.nativeEnum(Command),
-  error: ErrorPayloadSchema.optional(),
-  segments: SegmentPayloadSchema.array().nullable(),
-});
-
-type Response = z.infer<typeof ResponseSchema>;
-
-/**
- * Used to iterate over a clusters telemetry in time-order. It should not be
- * instantiated directly, and should instead be instantiated via the SegmentClient.
- *
- * Using an iterator is ideal when querying/processing large ranges of data, but
- * is relatively complex and difficult to use. If you're looking to retrieve
- *  telemetry between two timestamps, see the SegmentClient.read method.
- */
-export class CoreIterator {
-  private static ENDPOINT = '/segment/iterate';
-  private client: StreamClient;
-  private stream: Stream<Request, Response> | undefined;
-  private readonly aggregate: boolean = false;
-  values: SegmentPayload[] = [];
-
-  constructor(client: StreamClient, aggregate = false) {
-    this.client = client;
-    this.aggregate = aggregate;
-  }
-
-  /**
-   * Opens the iterator, configuring it to iterate over the telemetry in the
-   * channels with the given keys within the provided time range.
-   *
-   * @param tr - The time range to iterate over.
-   * @param keys - The keys of the channels to iterate over.
-   */
-  async open(tr: TimeRange, keys: string[]) {
-    this.stream = await this.client.stream(
-      CoreIterator.ENDPOINT,
-      RequestSchema,
-      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-      // @ts-ignore
-      ResponseSchema
-    );
-    await this.execute({ command: Command.Open, keys, range: tr });
-    this.values = [];
-  }
-
-  /**
-   * Reads the next segment for each channel in the iterator.
-   *
-   * @returns false if the next segment can't be found for one or more channels or
-   * the iterator has accumulated an error.
-   */
-  async next(): Promise<boolean> {
-    return this.execute({ command: Command.Next });
-  }
-
-  /**
-   * Reads the previous segment for each channel in the iterator.
-   *
-   * @returns false if the next segment can't be found for one or more channels or
-   * the iterator has accumulated an error.
-   */
-  async prev(): Promise<boolean> {
-    return this.execute({ command: Command.Prev });
-  }
-
-  /**
-   * Seeks to the beginning of the time range and reads the first segment of each
-   * channel in the iterator.
-   *
-   * @returns false if no segments exists in the time range for a particular channel
-   * or the iterator has accumulated an error.
-   */
-  async first(): Promise<boolean> {
-    return this.execute({ command: Command.First });
-  }
-
-  /**
-   * Seeks to the end of the time range and reads the last segment of each channel
-   * in the iterator.
-   *
-   * @returns false if no segments exists in the time range for a particular channel,
-   * or the iterator has accumulated an error.
-   */
-  async last(): Promise<boolean> {
-    return this.execute({ command: Command.Last });
-  }
-
-  /**
-   * Reads the next time span of telemetry for each channel in the iterator.
-   *
-   * @returns false if a segment satisfying the request can't be found for a
-   * particular channel or the iterator has accumulated an error.
-   */
-  async nextSpan(span: number): Promise<boolean> {
-    return this.execute({ command: Command.NextSpan, span });
-  }
-
-  /**
-   * Reads the previous time span of telemetry for each channel in the iterator.
-   *
-   * @returns false if a segment satisfying the request can't be found for a particular
-   * channel or the iterator has accumulated an error.
-   */
-  async prevSpan(span: number): Promise<boolean> {
-    return this.execute({ command: Command.PrevSpan, span });
-  }
-
-  /**
-   * Seeks the iterator to the start of the time range and reads the telemetry within
-   * the range for each channel.
-   *
-   * @returns: False if a segment satisfying the request can't be found for a particular
-   * channel or the iterator has accumulated an error.
-   */
-  async nextRange(range: TimeRange): Promise<boolean> {
-    return this.execute({ command: Command.NextRange, range });
-  }
-
-  /**
-   * Seeks the iterator to the first segment in the time range, but does not read
-   * it. Also invalidates the iterator. The iterator will not be considered valid
-   * until a call to first, last, next, prev, prev_span, next_span, or next_range.
-   *
-   * @returns false if the iterator is not pointing to a valid segment for a particular
-   * channel or has accumulated an error.
-   */
-  async seekFirst(): Promise<boolean> {
-    return this.execute({ command: Command.SeekFirst });
-  }
-
-  /** Seeks the iterator to the last segment in the time range, but does not read it.
-   * Also invalidates the iterator. The iterator will not be considered valid
-   * until a call to first, last, next, prev, prev_span, next_span, or next_range.
-   *
-   * @returns false if the iterator is not pointing to a valid segment for a particular
-   * channel or has accumulated an error.
-   */
-  async seekLast(): Promise<boolean> {
-    return this.execute({ command: Command.SeekLast });
-  }
-
-  /**
-   * Seeks the iterator to the first segment whose start is less than or equal to
-   * the provided timestamp. Also invalidates the iterator. The iterator will not be
-   * considered valid until a call to first, last, next, prev, prev_span, next_span, or next_range.
-   *
-   * @returns false if the iterator is not pointing to a valid segment for a particular
-   * channel or has accumulated an error.
-   */
-  async seekLT(stamp: number): Promise<boolean> {
-    return this.execute({ command: Command.SeekLT, stamp });
-  }
-
-  /**
-   * Seeks the iterator to the first segment whose start is greater than or equal to
-   * the provided timestamp. Also invalidates the iterator. The iterator will not be
-   * considered valid until a call to first, last, next, prev, prev_span, next_span, or next_range.
-   *
-   * @returns false if the iterator is not pointing to a valid segment for a particular
-   * channel or has accumulated an error.
-   */
-  async seekGE(stamp: number): Promise<boolean> {
-    return this.execute({ command: Command.SeekGE, stamp });
-  }
-
-  /**
-   * @returns true if the iterator value contains a valid segment, and fale otherwise.
-   * valid most commonly returns false when the iterator is exhausted or has
-   * accumulated an error.
-   */
-  async valid(): Promise<boolean> {
-    return this.execute({ command: Command.Valid });
-  }
-
-  /**
-   * Closes the iterator. An iterator MUST be closed after use, and this method
-   * should probably be placed in a 'finally' block. If the iterator is not closed,
-   * it may leak resources.
-   */
-  async close() {
-    if (!this.stream)
-      throw new Error('iterator.open() must be called before any other method');
-    this.stream.closeSend();
-    const [, exc] = await this.stream.receive();
-    if (!(exc instanceof EOF)) throw exc;
-  }
-
-  private async execute(request: Request): Promise<boolean> {
-    if (!this.stream)
-      throw new Error('iterator.open() must be called before any other method');
-    const err = this.stream.send(request);
-    if (err) throw err;
-    if (!this.aggregate) this.values = [];
-    for (;;) {
-      const [res, err] = await this.stream.receive();
-      if (err || !res) throw err;
-      if (res.variant == ResponseVariant.Ack) return res.ack;
-      if (res.segments) this.values.push(...res.segments);
-    }
-  }
-}
-
-export class TypedIterator extends CoreIterator {
-  channels: Registry;
-
-  constructor(client: StreamClient, channels: Registry, aggregate = false) {
-    super(client, aggregate);
-    this.channels = channels;
-  }
-
-  async value(): Promise<Record<string, TypedSegment>> {
-    const result: Record<string, TypedSegment> = {};
-    this.values.sort((a, b) => a.start.valueOf() - b.start.valueOf());
-    const keys = this.values.map((v) => v.channelKey);
-    const channels = await this.channels.getN(...keys);
-    this.values.forEach((v) => {
-      const sugared = new TypedSegment(
-        channels.find((c) => c.key == v.channelKey) as ChannelPayload,
-        v
-      );
-      if (v.channelKey in result) {
-        result[v.channelKey].extend(sugared);
-      } else {
-        result[v.channelKey] = sugared;
-      }
-    });
-    return result;
-  }
-}

package/src/lib/segment/payload.ts

@@ -1,18 +0,0 @@
-import { z } from 'zod';
-
-import { TimeStamp } from '../telem';
-
-export const SegmentPayloadSchema = z.object({
-  channelKey: z.string(),
-  start: z.number().transform((n) => new TimeStamp(n)),
-  data: z.string().transform(
-    (s) =>
-      new Uint8Array(
-        atob(s)
-          .split('')
-          .map((c) => c.charCodeAt(0))
-      )
-  ),
-});
-
-export type SegmentPayload = z.infer<typeof SegmentPayloadSchema>;