feat(packages): add shared package

packages/shared/src/constants/DisconnectReason.ts

@@ -0,0 +1,27 @@
+/**
+ * Disconnect reasons for clients
+ */
+enum DisconnectReason {
+    /**
+     * Unknown reason
+     */
+    Generic = 1,
+    /**
+     * The client did not respond in time
+     */
+    TimedOut,
+    /**
+     * The client sent an invalid packet (unserializable or invalid JSON)
+     */
+    InvalidPacket,
+    /**
+     * The server has encountered an internal error
+     */
+    ServerError,
+    /**
+     * The client had never connected to the server (**CLIENT-ONLY**) 
+     */
+    NeverConnected
+}
+
+export default DisconnectReason

packages/shared/src/constants/HumanizedDisconnectReason.ts

@@ -0,0 +1,11 @@
+import DisconnectReason from './DisconnectReason.js'
+
+const HumanizedDisconnectReason = {
+    [DisconnectReason.InvalidPacket]: 'has sent invalid packet',
+    [DisconnectReason.Generic]: 'has been disconnected for unknown reasons',
+    [DisconnectReason.TimedOut]: 'has timed out',
+    [DisconnectReason.ServerError]: 'has been disconnected due to an internal server error',
+    [DisconnectReason.NeverConnected]: 'had never connected to the server'
+} as const satisfies Record<DisconnectReason, string>
+
+export default HumanizedDisconnectReason

packages/shared/src/constants/Operation.ts

@@ -0,0 +1,57 @@
+/**
+ * Client operation codes for the gateway
+ */
+export enum ClientOperation {
+    /**
+     * Client's heartbeat (to check if the connection is dead or not)
+     */
+    Heartbeat = 100,
+
+    /**
+     * Client's request to parse text
+     */
+    ParseText = 110,
+    /**
+     * Client's request to parse image
+     */
+    ParseImage,
+}
+
+/**
+ * Server operation codes for the gateway
+ */
+export enum ServerOperation {
+    /**
+     * Server's acknowledgement of a client's heartbeat
+     */
+    HeartbeatAck = 1,
+    /**
+     * Server's initial response to a client's connection
+     */
+    Hello,
+
+    /**
+     * Server's response to client's request to parse text
+     */
+    ParsedText = 10,
+    /**
+     * Server's response to client's request to parse image
+     */
+    ParsedImage,
+    /**
+     * Server's failure response to client's request to parse text
+     */
+    ParseTextFailed,
+    /**
+     * Server's failure response to client's request to parse image
+     */
+    ParseImageFailed,
+
+    /**
+     * Server's disconnect message
+     */
+    Disconnect = 20
+}
+
+export const Operation = { ...ClientOperation, ...ServerOperation } as const
+export type Operation = (ClientOperation | ServerOperation)

packages/shared/src/constants/index.ts

@@ -0,0 +1,3 @@
+export { default as DisconnectReason } from './DisconnectReason.js'
+export { default as HumanizedDisconnectReason } from './HumanizedDisconnectReason.js'
+export * from './Operation.js'

packages/shared/src/index.ts

@@ -0,0 +1,3 @@
+export * from './constants/index.js'
+export * from './schemas/index.js'
+export * from './utils/index.js'

packages/shared/src/schemas/Packet.ts

@@ -0,0 +1,127 @@
+import DisconnectReason from '../constants/DisconnectReason.js'
+import {
+    ClientOperation,
+    Operation,
+    ServerOperation,
+} from '../constants/Operation.js'
+import {
+    object,
+    enum_,
+    special,
+    ObjectSchema,
+    number,
+    string,
+    Output,
+    AnySchema,
+    null_,
+    NullSchema,
+    array,
+    url,
+    parse,
+    // merge
+} from 'valibot'
+
+/**
+ * Schema to validate packets
+ */
+export const PacketSchema = special<Packet>(input => {
+    if (
+        typeof input === 'object' &&
+        input &&
+        'op' in input &&
+        typeof input.op === 'number' &&
+        input.op in Operation &&
+        'd' in input &&
+        typeof input.d === 'object'
+    ) {
+        try {
+            parse(PacketDataSchemas[input.op as Operation], input.d)
+            return true
+        } catch {
+            return false
+        }
+    }
+    return false
+}, 'Invalid packet data')
+
+// merge([
+//     object({
+//         op: nativeEnum(Operation, 'Not a valid operation number'),
+//     }),
+//     object({
+//         d: special<Packet['d']>(input => {
+//             if (
+//                 typeof input === 'object' &&
+//                 input &&
+//                 'op' in input &&
+//                 typeof input.op === 'number' &&
+//                 input.op in Operation &&
+//                 'd' in input &&
+//                 typeof input.d === 'object'
+//             ) {
+//                 try {
+//                     PacketDataSchemas[input.op as Operation].parse(input)
+//                     return true
+//                 } catch {
+//                     return false
+//                 }
+//             }
+//             return false
+//         }, 'Invalid packet data'),
+//     }),
+// ])
+
+/**
+ * Schema to validate packet data for each possible operations
+ */
+export const PacketDataSchemas = {
+    [ServerOperation.Hello]: object({
+        heartbeatInterval: number(),
+    }),
+    [ServerOperation.HeartbeatAck]: object({
+        nextHeartbeat: number(),
+    }),
+    [ServerOperation.ParsedText]: object({
+        id: string(),
+        labels: array(
+            object({
+                name: string(),
+                confidence: special<number>(
+                    input =>
+                        typeof input === 'number' && input >= 0 && input <= 1
+                ),
+            })
+        ),
+    }),
+    [ServerOperation.ParsedImage]: object({
+        id: string(),
+        text: string(),
+    }),
+    [ServerOperation.ParseTextFailed]: object({
+        id: string(),
+    }),
+    [ServerOperation.ParseImageFailed]: object({
+        id: string(),
+    }),
+    [ServerOperation.Disconnect]: object({
+        reason: enum_(DisconnectReason),
+    }),
+
+    [ClientOperation.Heartbeat]: null_(),
+    [ClientOperation.ParseText]: object({
+        id: string(),
+        text: string(),
+    }),
+    [ClientOperation.ParseImage]: object({
+        id: string(),
+        image_url: string([url()]),
+    }),
+} as const satisfies Record<
+    Operation,
+    ObjectSchema<any> | AnySchema | NullSchema
+>
+
+export type Packet<TOp extends Operation = Operation> = {
+    op: TOp
+    d: Output<(typeof PacketDataSchemas)[TOp]>
+}

packages/shared/src/schemas/index.ts

@@ -0,0 +1 @@
+export * from './Packet.js'

packages/shared/src/utils/guard.ts

@@ -0,0 +1,30 @@
+import { Packet } from '../schemas/Packet.js'
+import { ClientOperation, Operation, ServerOperation } from '../constants/Operation.js'
+
+/**
+ * Checks whether a packet is trying to do the given operation
+ * @param op Operation code to check
+ * @param packet A packet
+ * @returns Whether this packet is trying to do the operation given
+ */
+export function packetMatchesOperation<TOp extends Operation>(op: TOp, packet: Packet): packet is Packet<TOp> {
+    return packet.op === op
+}
+
+/**
+ * Checks whether this packet is a client packet **(this does NOT validate the data)**
+ * @param packet A packet
+ * @returns Whether this packet is a client packet
+ */
+export function isClientPacket(packet: Packet): packet is Packet<ClientOperation> {
+    return packet.op in ClientOperation
+}
+
+/**
+ * Checks whether this packet is a server packet **(this does NOT validate the data)**
+ * @param packet A packet
+ * @returns Whether this packet is a server packet
+ */
+export function isServerPacket(packet: Packet): packet is Packet<ServerOperation> {
+    return packet.op in ServerOperation
+}

packages/shared/src/utils/index.ts

@@ -0,0 +1,3 @@
+export * from './guard.js'
+export * from './serialization.js'
+export * from './string.js'

packages/shared/src/utils/serialization.ts

@@ -0,0 +1,23 @@
+import * as BSON from 'bson'
+import { Packet, PacketSchema } from '../schemas/index.js'
+import { Operation } from '../constants/index.js'
+import { parse } from 'valibot'
+
+/**
+ * Compresses a packet into a buffer
+ * @param packet The packet to compress
+ * @returns A buffer of the compressed packet
+ */
+export function serializePacket<TOp extends Operation>(packet: Packet<TOp>) {
+    return BSON.serialize(packet)
+}
+
+/**
+ * Decompresses a buffer into a packet
+ * @param buffer The buffer to decompress
+ * @returns A packet
+ */
+export function deserializePacket(buffer: Buffer) {
+    const data = BSON.deserialize(buffer)
+    return parse(PacketSchema, data) as Packet
+}

packages/shared/src/utils/string.ts

@@ -0,0 +1,3 @@
+export function uncapitalize<T extends string>(str: T): Uncapitalize<T> {
+    return str.charAt(0).toLowerCase() + str.slice(1) as Uncapitalize<T>
+}