@qualithm/arrow-flight-sql-js 0.1.0 → 0.2.0

package/dist/client.js

@@ -4,13 +4,12 @@
  * A TypeScript client for communicating with Arrow Flight SQL servers.
  * Modeled after the official Arrow Flight SQL clients (Java, C++, Go).
  */
-import * as grpc from "@grpc/grpc-js";
 import { RecordBatchReader } from "apache-arrow";
-import { collectToTable, parseFlightData, tryParseSchema } from "./arrow";
-import { AuthenticationError, ConnectionError, FlightSqlError } from "./errors";
-import { getFlightServiceDefinition } from "./generated";
-import { encodeActionClosePreparedStatementRequest, encodeActionCreatePreparedStatementRequest, encodeCommandGetCatalogs, encodeCommandGetDbSchemas, encodeCommandGetExportedKeys, encodeCommandGetImportedKeys, encodeCommandGetPrimaryKeys, encodeCommandGetTables, encodeCommandGetTableTypes, encodeCommandPreparedStatementQuery, encodeCommandStatementQuery, encodeCommandStatementUpdate, getBytesField, parseProtoFields } from "./proto";
-import { SubscriptionMessageType, SubscriptionMode } from "./types";
+import { collectToTable, parseFlightData, tryParseSchema } from "./arrow.js";
+import { AuthenticationError, ConnectionError, FlightSqlError } from "./errors.js";
+import { encodeActionClosePreparedStatementRequest, encodeActionCreatePreparedStatementRequest, encodeCommandGetCatalogs, encodeCommandGetDbSchemas, encodeCommandGetExportedKeys, encodeCommandGetImportedKeys, encodeCommandGetPrimaryKeys, encodeCommandGetTables, encodeCommandGetTableTypes, encodeCommandPreparedStatementQuery, encodeCommandStatementQuery, encodeCommandStatementUpdate, getBytesField, parseProtoFields, unwrapAny } from "./proto.js";
+import { getTransportForRuntime } from "./transport-grpc-js.js";
+import { SubscriptionMessageType, SubscriptionMode } from "./types.js";
 // Default configuration values
 const defaultConnectTimeoutMs = 30_000;
 const defaultRequestTimeoutMs = 60_000;
@@ -38,8 +37,7 @@ const defaultRequestTimeoutMs = 60_000;
  */
 export class FlightSqlClient {
     options;
-    grpcClient = null;
-    flightService = null;
+    transport = null;
     authToken = null;
     connected = false;
     constructor(options) {
@@ -50,6 +48,10 @@ export class FlightSqlClient {
             connectTimeoutMs: options.connectTimeoutMs ?? defaultConnectTimeoutMs,
             requestTimeoutMs: options.requestTimeoutMs ?? defaultRequestTimeoutMs
         };
+        // Use provided transport or create one for the runtime
+        if (options.transport !== undefined) {
+            this.transport = options.transport;
+        }
     }
     // ===========================================================================
     // Connection Lifecycle
@@ -65,25 +67,17 @@ export class FlightSqlClient {
             return;
         }
         try {
-            // Load the Flight service definition
-            const packageDef = await getFlightServiceDefinition();
-            // Navigate to arrow.flight.protocol.FlightService
-            const arrowPackage = packageDef.arrow;
-            const flightPackage = arrowPackage.flight;
-            const protocolPackage = flightPackage.protocol;
-            this.flightService = protocolPackage.FlightService;
-            // Create channel credentials
-            const credentials = this.options.credentials ?? this.createCredentials();
-            // Create the gRPC client
-            const address = `${this.options.host}:${String(this.options.port)}`;
-            this.grpcClient = new this.flightService(address, credentials, {
-                "grpc.max_receive_message_length": -1, // Unlimited
-                "grpc.max_send_message_length": -1,
-                "grpc.keepalive_time_ms": 30_000,
-                "grpc.keepalive_timeout_ms": 10_000
+            // Create transport if not provided
+            this.transport ??= getTransportForRuntime({
+                host: this.options.host,
+                port: this.options.port,
+                tls: this.options.tls,
+                credentials: this.options.credentials,
+                connectTimeoutMs: this.options.connectTimeoutMs,
+                requestTimeoutMs: this.options.requestTimeoutMs
             });
-            // Wait for the channel to be ready
-            await this.waitForReady();
+            // Connect the transport
+            await this.transport.connect();
             // Perform authentication handshake if configured
             if (this.options.auth && this.options.auth.type !== "none") {
                 await this.authenticate(this.options.auth);
@@ -215,12 +209,19 @@ export class FlightSqlClient {
         let datasetSchema = null;
         let parameterSchema = null;
         for await (const result of this.doAction(action)) {
+            // The result body may be wrapped in a protobuf Any envelope
+            // Try to unwrap it first, otherwise parse directly
+            let messageBytes = result.body;
+            const anyWrapper = unwrapAny(result.body);
+            if (anyWrapper) {
+                messageBytes = anyWrapper.value;
+            }
             // Parse ActionCreatePreparedStatementResult
             // Fields:
             //   1: prepared_statement_handle (bytes)
             //   2: dataset_schema (bytes) - Arrow IPC schema
             //   3: parameter_schema (bytes) - Arrow IPC schema
-            const fields = parseProtoFields(result.body);
+            const fields = parseProtoFields(messageBytes);
             handle = getBytesField(fields, 1);
             const datasetSchemaBytes = getBytesField(fields, 2);
             const parameterSchemaBytes = getBytesField(fields, 3);
@@ -519,19 +520,19 @@ export class FlightSqlClient {
      * @returns FlightInfo with schema and endpoints
      */
     async getFlightInfo(descriptor) {
-        this.ensureConnected();
-        return new Promise((resolve, reject) => {
-            const client = this.grpcClient;
+        const transport = this.getConnectedTransport();
+        try {
             const metadata = this.createRequestMetadata();
-            const request = this.serializeFlightDescriptor(descriptor);
-            client.getFlightInfo(request, metadata, (error, response) => {
-                if (error) {
-                    reject(this.wrapGrpcError(error));
-                    return;
-                }
-                resolve(this.parseFlightInfo(response));
-            });
-        });
+            const rawInfo = await transport.getFlightInfo({
+                type: descriptor.type,
+                cmd: descriptor.cmd,
+                path: descriptor.path
+            }, metadata);
+            return this.parseFlightInfo(rawInfo);
+        }
+        catch (error) {
+            throw this.wrapTransportError(error);
+        }
     }
     /**
      * Get the schema for a flight descriptor without fetching data.
@@ -540,19 +541,19 @@ export class FlightSqlClient {
      * @returns Schema result
      */
     async getSchema(descriptor) {
-        this.ensureConnected();
-        return new Promise((resolve, reject) => {
-            const client = this.grpcClient;
+        const transport = this.getConnectedTransport();
+        try {
             const metadata = this.createRequestMetadata();
-            const request = this.serializeFlightDescriptor(descriptor);
-            client.getSchema(request, metadata, (error, response) => {
-                if (error) {
-                    reject(this.wrapGrpcError(error));
-                    return;
-                }
-                resolve(this.parseSchemaResult(response));
-            });
-        });
+            const rawSchema = await transport.getSchema({
+                type: descriptor.type,
+                cmd: descriptor.cmd,
+                path: descriptor.path
+            }, metadata);
+            return this.parseSchemaResult(rawSchema);
+        }
+        catch (error) {
+            throw this.wrapTransportError(error);
+        }
     }
     /**
      * Retrieve data for a ticket as an async iterator of FlightData.
@@ -561,17 +562,20 @@ export class FlightSqlClient {
      * @yields FlightData chunks containing dataHeader and dataBody
      */
     async *doGet(ticket) {
-        this.ensureConnected();
-        const client = this.grpcClient;
+        const transport = this.getConnectedTransport();
         const metadata = this.createRequestMetadata();
-        const request = { ticket: ticket.ticket };
-        const stream = client.doGet(request, metadata);
+        const stream = transport.doGet({ ticket: ticket.ticket }, metadata);
         try {
-            for await (const data of this.wrapStream(stream)) {
-                const flightData = data;
-                yield flightData;
+            for await (const data of stream) {
+                yield {
+                    dataHeader: data.dataHeader,
+                    dataBody: data.dataBody
+                };
             }
         }
+        catch (error) {
+            throw this.wrapTransportError(error);
+        }
         finally {
             stream.cancel();
         }
@@ -584,16 +588,10 @@ export class FlightSqlClient {
      * @returns Async iterator of PutResult messages
      */
     async *doPut(descriptor, dataStream) {
-        this.ensureConnected();
-        const client = this.grpcClient;
+        const transport = this.getConnectedTransport();
         const requestMetadata = this.createRequestMetadata();
         // Create bidirectional stream
-        const stream = client.doPut(requestMetadata);
-        // Use object wrapper to track errors (allows TypeScript to understand mutation)
-        const errorState = { error: null };
-        stream.on("error", (err) => {
-            errorState.error = err;
-        });
+        const stream = transport.doPut(requestMetadata);
         // Send the first message with the descriptor
         const firstData = await this.getFirstFromIterable(dataStream);
         if (firstData) {
@@ -606,9 +604,6 @@ export class FlightSqlClient {
         }
         // Send remaining data
         for await (const data of dataStream) {
-            if (errorState.error) {
-                throw this.wrapGrpcError(errorState.error);
-            }
             stream.write({
                 dataHeader: data.dataHeader,
                 dataBody: data.dataBody,
@@ -619,16 +614,12 @@ export class FlightSqlClient {
         stream.end();
         // Read responses
         try {
-            for await (const result of this.wrapStream(stream)) {
-                const putResult = result;
-                yield { appMetadata: putResult.appMetadata };
+            for await (const result of stream) {
+                yield { appMetadata: result.appMetadata };
             }
         }
         catch (error) {
-            if (errorState.error) {
-                throw this.wrapGrpcError(errorState.error);
-            }
-            throw error;
+            throw this.wrapTransportError(error);
         }
     }
     /**
@@ -662,25 +653,15 @@ export class FlightSqlClient {
      * ```
      */
     doExchange(descriptor) {
-        this.ensureConnected();
-        const client = this.grpcClient;
+        const transport = this.getConnectedTransport();
         const metadata = this.createRequestMetadata();
-        const stream = client.doExchange(metadata);
-        // Use object wrapper to track errors
-        const errorState = { error: null };
-        stream.on("error", (err) => {
-            errorState.error = err;
-        });
+        const stream = transport.doExchange(metadata);
         // Capture references for closure
-        const wrapGrpcError = this.wrapGrpcError.bind(this);
+        const wrapTransportError = this.wrapTransportError.bind(this);
         const serializeFlightDescriptor = this.serializeFlightDescriptor.bind(this);
-        const wrapStream = this.wrapStream.bind(this);
         // Create the exchange handle
         const exchange = {
             async send(data) {
-                if (errorState.error) {
-                    throw wrapGrpcError(errorState.error);
-                }
                 stream.write({
                     flightDescriptor: data.flightDescriptor
                         ? serializeFlightDescriptor(data.flightDescriptor)
@@ -700,27 +681,23 @@ export class FlightSqlClient {
             },
             async *[Symbol.asyncIterator]() {
                 try {
-                    for await (const data of wrapStream(stream)) {
-                        const flightData = data;
+                    for await (const data of stream) {
                         yield {
-                            flightDescriptor: flightData.flightDescriptor
+                            flightDescriptor: data.flightDescriptor
                                 ? {
-                                    type: flightData.flightDescriptor.type,
-                                    cmd: flightData.flightDescriptor.cmd,
-                                    path: flightData.flightDescriptor.path
+                                    type: data.flightDescriptor.type,
+                                    cmd: data.flightDescriptor.cmd,
+                                    path: data.flightDescriptor.path
                                 }
                                 : undefined,
-                            dataHeader: flightData.dataHeader ?? new Uint8Array(),
-                            dataBody: flightData.dataBody ?? new Uint8Array(),
-                            appMetadata: flightData.appMetadata
+                            dataHeader: data.dataHeader ?? new Uint8Array(),
+                            dataBody: data.dataBody ?? new Uint8Array(),
+                            appMetadata: data.appMetadata
                         };
                     }
                 }
                 catch (error) {
-                    if (errorState.error) {
-                        throw wrapGrpcError(errorState.error);
-                    }
-                    throw error;
+                    throw wrapTransportError(error);
                 }
             }
         };
@@ -779,16 +756,17 @@ export class FlightSqlClient {
      * @returns Async iterator of results
      */
     async *doAction(action) {
-        this.ensureConnected();
-        const client = this.grpcClient;
+        const transport = this.getConnectedTransport();
         const metadata = this.createRequestMetadata();
-        const request = { type: action.type, body: action.body };
-        const stream = client.doAction(request, metadata);
+        const stream = transport.doAction({ type: action.type, body: action.body }, metadata);
         try {
-            for await (const result of this.wrapStream(stream)) {
-                yield result;
+            for await (const result of stream) {
+                yield { body: result.body ?? new Uint8Array() };
             }
         }
+        catch (error) {
+            throw this.wrapTransportError(error);
+        }
         finally {
             stream.cancel();
         }
@@ -799,13 +777,20 @@ export class FlightSqlClient {
      * @returns Array of available action types
      */
     async listActions() {
-        this.ensureConnected();
-        const client = this.grpcClient;
+        const transport = this.getConnectedTransport();
         const metadata = this.createRequestMetadata();
-        const stream = client.listActions({}, metadata);
+        const stream = transport.listActions(metadata);
         const actions = [];
-        for await (const action of this.wrapStream(stream)) {
-            actions.push(action);
+        try {
+            for await (const action of stream) {
+                actions.push({
+                    type: action.type,
+                    description: action.description ?? ""
+                });
+            }
+        }
+        catch (error) {
+            throw this.wrapTransportError(error);
         }
         return actions;
     }
@@ -833,30 +818,35 @@ export class FlightSqlClient {
         }
     }
     async handshake(username, password) {
-        return new Promise((resolve, reject) => {
-            const client = this.grpcClient;
-            const stream = client.handshake();
-            // Build BasicAuth payload
-            const authPayload = this.encodeBasicAuth(username, password);
-            stream.on("data", (response) => {
-                resolve({
-                    protocolVersion: BigInt(response.protocolVersion ?? "0"),
-                    payload: response.payload ?? new Uint8Array()
-                });
-            });
-            stream.on("error", (error) => {
-                reject(new AuthenticationError("Handshake failed", { cause: error }));
-            });
-            stream.on("end", () => {
-                // Stream ended without response
-            });
-            // Send handshake request
-            stream.write({
-                protocolVersion: "1",
-                payload: authPayload
-            });
-            stream.end();
+        // Note: Called during connect(), so transport exists but connected flag isn't set yet
+        if (this.transport === null) {
+            throw new ConnectionError("Transport not initialized");
+        }
+        const stream = this.transport.handshake();
+        // Build BasicAuth payload
+        const authPayload = this.encodeBasicAuth(username, password);
+        // Send handshake request
+        stream.write({
+            protocolVersion: 1,
+            payload: authPayload
         });
+        stream.end();
+        // Read response
+        try {
+            for await (const response of stream) {
+                return {
+                    protocolVersion: BigInt(response.protocolVersion ?? 0),
+                    payload: response.payload ?? new Uint8Array()
+                };
+            }
+            throw new AuthenticationError("Handshake failed: no response received");
+        }
+        catch (error) {
+            if (error instanceof AuthenticationError) {
+                throw error;
+            }
+            throw new AuthenticationError("Handshake failed", { cause: error });
+        }
     }
     encodeBasicAuth(username, password) {
         // Simple encoding: "username:password" as UTF-8 bytes
@@ -865,101 +855,62 @@ export class FlightSqlClient {
         return encoder.encode(`${username}:${password}`);
     }
     // ===========================================================================
-    // Private: gRPC Helpers
+    // Private: Transport Helpers
     // ===========================================================================
-    createCredentials() {
-        if (this.options.tls) {
-            return grpc.credentials.createSsl();
-        }
-        return grpc.credentials.createInsecure();
-    }
-    async waitForReady() {
-        return new Promise((resolve, reject) => {
-            const deadline = Date.now() + this.options.connectTimeoutMs;
-            const client = this.grpcClient;
-            if (!client) {
-                reject(new ConnectionError("gRPC client not initialized"));
-                return;
-            }
-            client.waitForReady(deadline, (error) => {
-                if (error) {
-                    reject(new ConnectionError("Connection timeout", { cause: error }));
-                }
-                else {
-                    resolve();
-                }
-            });
-        });
-    }
     createRequestMetadata() {
-        const metadata = new grpc.Metadata();
+        const metadata = {};
         // Add auth token if present
         if (this.authToken !== null && this.authToken !== "") {
-            metadata.set("authorization", `Bearer ${this.authToken}`);
+            metadata.authorization = `Bearer ${this.authToken}`;
         }
         // Add custom metadata from options
         if (this.options.metadata) {
             for (const [key, value] of Object.entries(this.options.metadata)) {
-                metadata.set(key, value);
+                metadata[key] = value;
             }
         }
         return metadata;
     }
     cleanup() {
-        if (this.grpcClient) {
-            this.grpcClient.close();
-            this.grpcClient = null;
+        if (this.transport) {
+            this.transport.close();
+            this.transport = null;
         }
-        this.flightService = null;
         this.authToken = null;
         this.connected = false;
     }
     ensureConnected() {
-        if (!this.connected) {
+        if (!this.connected || this.transport === null) {
             throw new ConnectionError("Client is not connected. Call connect() first.");
         }
     }
-    wrapGrpcError(error) {
-        const message = error.details || error.message;
-        switch (error.code) {
-            case grpc.status.UNAUTHENTICATED:
-                return new AuthenticationError(message, { cause: error });
-            case grpc.status.UNAVAILABLE:
-            case grpc.status.DEADLINE_EXCEEDED:
-                return new ConnectionError(message, { cause: error });
-            case grpc.status.OK:
-            case grpc.status.CANCELLED:
-            case grpc.status.UNKNOWN:
-            case grpc.status.INVALID_ARGUMENT:
-            case grpc.status.NOT_FOUND:
-            case grpc.status.ALREADY_EXISTS:
-            case grpc.status.PERMISSION_DENIED:
-            case grpc.status.RESOURCE_EXHAUSTED:
-            case grpc.status.FAILED_PRECONDITION:
-            case grpc.status.ABORTED:
-            case grpc.status.OUT_OF_RANGE:
-            case grpc.status.UNIMPLEMENTED:
-            case grpc.status.INTERNAL:
-            case grpc.status.DATA_LOSS:
-                return new FlightSqlError(message, { cause: error });
-        }
-    }
-    // ===========================================================================
-    // Private: Streaming Helpers
-    // ===========================================================================
     /**
-     * Wraps a gRPC stream to convert errors to FlightSqlError types.
-     * gRPC streams are already async iterable, so we just need error handling.
+     * Get the transport, throwing if not connected.
+     * This is a helper to avoid non-null assertions after ensureConnected().
      */
-    async *wrapStream(stream) {
-        try {
-            for await (const data of stream) {
-                yield data;
-            }
+    getConnectedTransport() {
+        if (!this.connected || this.transport === null) {
+            throw new ConnectionError("Client is not connected. Call connect() first.");
         }
-        catch (error) {
-            throw this.wrapGrpcError(error);
+        return this.transport;
+    }
+    wrapTransportError(error) {
+        // Handle TransportError with gRPC status codes
+        const transportError = error;
+        const message = transportError.details ?? error.message;
+        if (transportError.code !== undefined) {
+            // gRPC status codes
+            switch (transportError.code) {
+                case 16: // UNAUTHENTICATED
+                    return new AuthenticationError(message, { cause: error });
+                case 14: // UNAVAILABLE
+                case 4: // DEADLINE_EXCEEDED
+                    return new ConnectionError(message, { cause: error });
+                default:
+                    return new FlightSqlError(message, { cause: error });
+            }
         }
+        return new FlightSqlError(message, { cause: error });
     }
     // ===========================================================================
     // Private: Serialization Helpers