@grest-ts/http 0.0.5

package/src/rpc/RpcRequest/GGRpcRequestBuilder.ts

@@ -0,0 +1,91 @@
+import type {HttpMethod} from "@grest-ts/common";
+import {GGContractMethod} from "@grest-ts/schema";
+import {ClientHttpRouteToRpcTransformClientConfig, GGHttpFetchRequest, GGHttpTransportMiddleware} from "../../schema/GGHttpSchema";
+
+export class GGRpcRequestBuilder {
+
+    public readonly contract: GGContractMethod
+    public readonly middlewares: readonly GGHttpTransportMiddleware[]
+    public readonly method: HttpMethod;
+    public readonly pathTemplate: string;
+    public readonly pathParams: string[];
+    public readonly pathPrefix: string;
+    public readonly hasBody: boolean;
+
+    constructor(
+        method: HttpMethod,
+        pathTemplate: string,
+        config: ClientHttpRouteToRpcTransformClientConfig
+    ) {
+        this.method = method
+        this.pathTemplate = pathTemplate
+        this.pathPrefix = config.pathPrefix
+        this.contract = config.contract
+        this.middlewares = config.middlewares
+        this.pathParams = (pathTemplate.match(/:(\w+)/g) || []).map(m => m.slice(1))
+        this.hasBody = method === "POST" || method === "PUT" || method === "PATCH"
+    }
+
+    public createRequest = (data: unknown): GGHttpFetchRequest => {
+        let result: GGHttpFetchRequest;
+        if (this.hasBody) {
+            result = {
+                url: this.pathPrefix + this.buildPath(data),
+                method: this.method,
+                headers: {'Content-Type': 'application/json'},
+                body: this.buildBody(data)
+            }
+        } else {
+            result = {
+                url: this.pathPrefix + this.buildPath(data) + this.buildQueryString(data as Record<string, unknown>),
+                method: this.method,
+                headers: {},
+                body: undefined
+            }
+        }
+        this.middlewares?.forEach(mw => mw.updateRequest?.(result))
+        return result
+    }
+
+    private buildPath(data: unknown) {
+        let path: string = this.pathTemplate;
+        if (this.pathParams.length > 0 && typeof data === "object" && data) {
+            for (let i = 0; i < this.pathParams.length; i++) {
+                const p = this.pathParams[i]
+                const val = (data as Record<string, unknown>)[p]
+                path = path.replace(':' + p, encodeURIComponent(val === undefined || val === null ? "" : String(val)))
+            }
+        }
+        return path;
+    }
+
+    private buildBody(data: unknown) {
+        if (data === undefined || data === null) {
+            return undefined;
+        }
+        if (this.contract.input?.def.hasNonJsonData) {
+            throw new Error("Schema contains non-JSON data (e.g. files). Use GGRpc.MULTIPART_POST instead of GGRpc.POST for this route.")
+        } else {
+            return JSON.stringify(data)
+        }
+    }
+
+    private buildQueryString(data: unknown): string {
+        if (data && typeof data === "object") {
+            const params = new URLSearchParams()
+            for (const [key, value] of Object.entries(data)) {
+                if (value !== undefined && value !== null) {
+                    if (this.pathParams.length > 0 && this.pathParams.includes(key)) {
+                        continue;
+                    }
+                    params.append(key, String(value))
+                }
+            }
+            const query = params.toString()
+            if (query) {
+                return "?" + query
+            }
+        }
+        return ""
+    }
+}

package/src/rpc/RpcRequest/GGRpcRequestParser.ts

@@ -0,0 +1,100 @@
+import type http from "http";
+import type {HttpMethod} from "@grest-ts/common";
+import {GGContractExecutor, GGContractMethod} from "@grest-ts/schema";
+import {ClientHttpRouteToRpcTransformServerConfig, GGHttpRequest, GGHttpTransportMiddleware} from "../../schema/GGHttpSchema";
+import type {GGHttpServerMiddleware} from "../../server/GGHttpSchema.startServer";
+
+export class GGRpcRequestParser {
+
+    private readonly pathTemplate: string;
+    private readonly pathParams: string[];
+    private readonly hasBody: boolean;
+    protected readonly contract: GGContractMethod
+    private readonly apiMiddlewares: readonly GGHttpTransportMiddleware[]
+    private readonly serverMiddlewares: readonly GGHttpServerMiddleware[]
+
+    constructor(
+        method: HttpMethod,
+        pathTemplate: string,
+        config: ClientHttpRouteToRpcTransformServerConfig
+    ) {
+        this.pathTemplate = pathTemplate
+        this.pathParams = (pathTemplate.match(/:(\w+)/g) || []).map(m => m.slice(1))
+        this.hasBody = method === "POST" || method === "PUT" || method === "PATCH"
+        this.contract = config.contract
+        this.apiMiddlewares = config.apiMiddlewares
+        this.serverMiddlewares = config.serverMiddlewares
+    }
+
+    public parseRequest = async (req: http.IncomingMessage): Promise<unknown> => {
+        const url = req.url || '/'
+        const qIndex = url.indexOf('?')
+        const queryArgs = this.parseQueryString(qIndex === -1 ? '' : url.substring(qIndex + 1))
+        if (this.apiMiddlewares?.length > 0) {
+            const mwQuery: GGHttpRequest = {headers: req.headers, queryArgs: queryArgs}
+            this.apiMiddlewares?.forEach(mw => mw.parseRequest?.(mwQuery))
+        }
+        for (const mw of this.serverMiddlewares ?? []) await mw.process?.();
+
+        let input: unknown;
+        if (this.hasBody) {
+            input = await this.parseBody(req);
+        } else if (this.pathParams.length > 0) {
+            input = {
+                ...this.extractPathParams(qIndex === -1 ? url : url.substring(0, qIndex)),
+                ...queryArgs
+            };
+        } else {
+            input = queryArgs;
+        }
+        return GGContractExecutor.parseInput(this.contract.input, input);
+    }
+
+    private parseQueryString(rawQuery: string): Record<string, string | string[]> {
+        const result: Record<string, string | string[]> = {}
+        if (rawQuery) {
+            const params = new URLSearchParams(rawQuery)
+            for (const [key, value] of params.entries()) {
+                result[key] = value
+            }
+        }
+        return result;
+    }
+
+    private extractPathParams(actualPath: string): Record<string, string> {
+        const result: Record<string, string> = {}
+        const templateParts = this.pathTemplate.split('/').filter(p => p)
+        const actualParts = actualPath.split('/').filter(p => p)
+        const offset = actualParts.length - templateParts.length
+        if (offset >= 0) {
+            for (let i = 0; i < templateParts.length; i++) {
+                const templatePart = templateParts[i]
+                if (templatePart.startsWith(':')) {
+                    const paramName = templatePart.slice(1)
+                    result[paramName] = decodeURIComponent(actualParts[offset + i] || '')
+                }
+            }
+        }
+        return result;
+    }
+
+    private async parseBody(req: http.IncomingMessage): Promise<unknown> {
+        const contentType = req.headers['content-type'] || ''
+        const isMultipart = contentType.toLowerCase().startsWith('multipart/form-data')
+        if (isMultipart) {
+            throw new Error("Received multipart request on a JSON-only route. Use GGRpc.MULTIPART_POST for routes with file uploads.")
+        } else {
+            const rawBody: Buffer = await new Promise((resolve, reject) => {
+                const chunks: Buffer[] = []
+                req.on('data', (chunk: Buffer) => chunks.push(chunk))
+                req.on('end', () => resolve(Buffer.concat(chunks)))
+                req.on('error', reject)
+            });
+            if (rawBody && rawBody.length > 0) {
+                return JSON.parse(rawBody.toString('utf-8'))
+            } else {
+                return undefined
+            }
+        }
+    }
+}

package/src/rpc/RpcResponse/GGRpcResponseBuilder.ts

@@ -0,0 +1,84 @@
+import type http from "http";
+import {ANY_ERROR, ERROR, GGContractExecutor, GGContractMethod, GGDebugData, GGErrorData, GGSchema, OK} from "@grest-ts/schema";
+import {ClientHttpRouteToRpcTransformServerConfig} from "../../schema/GGHttpSchema";
+
+
+export class GGRpcResponseBuilder {
+
+    protected readonly contract: GGContractMethod
+
+    constructor(config: ClientHttpRouteToRpcTransformServerConfig) {
+        this.contract = config.contract;
+    }
+
+    public sendResponse = async (res: http.ServerResponse, rpcResult: ERROR<string, unknown> | OK<unknown>): Promise<void> => {
+        let json: string;
+        let statusCode: number;
+        if (rpcResult.success === true) {
+            statusCode = 200;
+            json = '{' +
+                '"success":true,' +
+                '"type":"OK"' +
+                this.makeDataStr(this.contract.success, rpcResult) +
+                "}"
+        } else {
+            json = this.makeError(GGContractExecutor.getResponseSchema(this.contract, rpcResult), rpcResult);
+            statusCode = rpcResult.statusCode;
+        }
+        res.writeHead(statusCode, {
+            'Content-Type': 'application/json',
+            'Content-Length': Buffer.byteLength(json)
+        });
+        res.end(json)
+    }
+
+    private makeError(schema: GGSchema<any> | undefined, rpcResult: ERROR<string, unknown>) {
+        return '{' +
+            '"success":false,' +
+            '"type":' + JSON.stringify(rpcResult.type) + ',' +
+            '"statusCode":' + Number(rpcResult.statusCode) +
+            this.makeErrorCtx(rpcResult.context, rpcResult.getDebugContext()) +
+            this.makeDataStr(schema, rpcResult) +
+            "}";
+    }
+
+    private makeDataStr(schema: GGSchema<any>, data: OK<any> | ANY_ERROR): string {
+        if (schema) {
+            GGContractExecutor.assertResponse(schema, data);
+            const dataStr = schema.unsafeStringify(data.data)
+            return dataStr ? ',"data":' + dataStr + "" : "";
+        } else {
+            return "";
+        }
+    }
+
+    private makeErrorCtx(ctx: GGErrorData, debugContext?: GGDebugData): string {
+        if (ctx) {
+            let str = "";
+            str += ctx?.displayMessage ? '"displayMessage":' + JSON.stringify(ctx.displayMessage) + '' : "";
+            str += ctx?.timestamp ? (str ? "," : "") + '"timestamp":' + Number(ctx.timestamp) : "";
+            str += ctx?.ref ? (str ? "," : "") + '"ref":' + JSON.stringify(ctx.ref) + '' : "";
+            if (process.env.NODE_ENV !== "production" && debugContext) {
+                if (debugContext?.debugMessage) {
+                    str += (str ? "," : "") + '"debugMessage":' + JSON.stringify(debugContext.debugMessage);
+                }
+                if (debugContext?.debugData !== undefined) {
+                    str += (str ? "," : "") + '"debugData":' + JSON.stringify(debugContext.debugData);
+                }
+                if (debugContext?.originalError) {
+                    const origErr = debugContext.originalError;
+                    const errInfo = origErr instanceof ERROR
+                        ? origErr.toJSON()
+                        : origErr instanceof Error
+                            ? {message: origErr.message, stack: origErr.stack?.split("\n")}
+                            : {message: String(origErr)};
+                    str += (str ? "," : "") + '"originalError":' + JSON.stringify(errInfo);
+                }
+            }
+            if (str) {
+                return ',"context":{' + str + '}';
+            }
+        }
+        return "";
+    }
+}

package/src/rpc/RpcResponse/GGRpcResponseParser.ts

@@ -0,0 +1,23 @@
+import {ERROR_JSON, OK, SERVER_ERROR} from "@grest-ts/schema";
+import {ClientHttpRouteToRpcTransformClientConfig} from "../../schema/GGHttpSchema";
+
+export class GGRpcResponseParser {
+
+    constructor(config: ClientHttpRouteToRpcTransformClientConfig) {
+
+    }
+
+    parseResponse = async (response: Response): Promise<OK<unknown> | ERROR_JSON<string, unknown>> => {
+        const txt = await response.text();
+        try {
+            const json = txt ? JSON.parse(txt) : {};
+            if (typeof json === "object" && "success" in json && "type" in json) {
+                return json
+            } else {
+                return new SERVER_ERROR({displayMessage: "Invalid response format!", debugData: {json: json}});
+            }
+        } catch (err) {
+            return new SERVER_ERROR({displayMessage: "Failed to parse JSON", originalError: err, debugData: {text: txt}});
+        }
+    }
+}

package/src/schema/GGHttpSchema.ts

@@ -0,0 +1,115 @@
+import {ERROR, ERROR_JSON, GGContractApiDefinition, GGContractClass, GGContractMethod, OK} from "@grest-ts/schema";
+import type {HttpMethod} from "@grest-ts/common";
+import type http from "http";
+import type {GGHttpServerMiddleware} from "../server/GGHttpSchema.startServer";
+
+export class GGHttpSchema<TContract extends GGContractApiDefinition, TContext> {
+
+    public readonly name: string
+    public readonly pathPrefix: string
+    public readonly apiMiddlewares: readonly GGHttpTransportMiddleware[]
+    public readonly codec: Record<keyof TContract, GGHttpCodec>
+    public readonly contract: GGContractClass<TContract> | null = null
+
+    constructor(
+        pathPrefix: string,
+        contract: GGContractClass<TContract>,
+        wireCodec: Record<keyof TContract, GGHttpCodec>,
+        middlewares: readonly GGHttpTransportMiddleware[] = []
+    ) {
+        this.name = contract.name
+        this.pathPrefix = pathPrefix
+        this.apiMiddlewares = middlewares
+        this.codec = wireCodec
+        this.contract = contract
+        Object.freeze(this.apiMiddlewares)
+        Object.freeze(this.codec)
+        Object.freeze(this)
+    }
+}
+
+// --------------------------------------------------------------------------------------------------------
+// Client codec
+// --------------------------------------------------------------------------------------------------------
+
+export interface ClientHttpRouteToRpcTransformClientConfig {
+    pathPrefix: string,
+    contract: GGContractMethod,
+    middlewares: readonly GGHttpTransportMiddleware[]
+}
+
+export interface ClientHttpRouteToRpcTransformClientCodec {
+    createRequest: (data: unknown) => GGHttpFetchRequest | Promise<GGHttpFetchRequest>
+    parseResponse: (response: Response) => Promise<OK<unknown> | ERROR_JSON<string, unknown>>
+}
+
+export interface GGHttpFetchRequest {
+    url: string;
+    method: HttpMethod;
+    headers: Record<string, string>;
+    body: string | FormData | undefined;
+}
+
+// --------------------------------------------------------------------------------------------------------
+// Server codec
+// --------------------------------------------------------------------------------------------------------
+
+export interface ClientHttpRouteToRpcTransformServerConfig {
+    contract: GGContractMethod,
+    apiMiddlewares: readonly GGHttpTransportMiddleware[],
+    serverMiddlewares: readonly GGHttpServerMiddleware[]
+}
+
+export interface ClientHttpRouteToRpcTransformServerCodec {
+    parseRequest: (req: http.IncomingMessage) => Promise<unknown>,
+    sendResponse: (res: http.ServerResponse, rpcResult: ERROR<string, unknown> | OK<unknown>) => Promise<void>
+}
+
+// --------------------------------------------------------------------------------------------------------
+// Codec
+// --------------------------------------------------------------------------------------------------------
+
+export interface GGHttpCodec {
+    readonly method: HttpMethod;
+    readonly path: string;
+
+    createForClient(config: ClientHttpRouteToRpcTransformClientConfig): ClientHttpRouteToRpcTransformClientCodec
+
+    createForServer(config: ClientHttpRouteToRpcTransformServerConfig): ClientHttpRouteToRpcTransformServerCodec
+
+}
+
+// --------------------------------------------------------------------------------------------------------
+// Middleware
+// --------------------------------------------------------------------------------------------------------
+
+export interface GGHttpTransportMiddleware {
+    /**
+     * Client-side: modify outgoing request (add headers, etc.)
+     */
+    updateRequest?(req: GGHttpRequest): void;
+
+    /**
+     * Server-side: parse incoming request (extract context from headers, etc.)
+     */
+    parseRequest?(req: GGHttpRequest): void;
+
+    /**
+     * Server-side: modify outgoing response
+     */
+    updateResponse?(res: GGHttpResponse): void;
+
+    /**
+     * Client-side: parse incoming response
+     */
+    parseResponse?(res: GGHttpResponse): void;
+}
+
+export interface GGHttpRequest {
+    headers?: Record<string, string | string[]>;
+    queryArgs?: Record<string, string | string[]>;
+}
+
+export interface GGHttpResponse {
+    headers: Record<string, string | string[]>;
+}

package/src/schema/httpSchema.ts

@@ -0,0 +1,99 @@
+import type http from "http";
+import {GGHttpCodec, GGHttpSchema} from "./GGHttpSchema";
+import {GGHttpRequest, GGHttpTransportMiddleware} from "./GGHttpSchema";
+import {GGContractApiDefinition, GGContractClass} from "@grest-ts/schema";
+import {GGContextKey} from "@grest-ts/context";
+
+/**
+ * Create an HTTP API schema builder from a contract.
+ *
+ * @example
+ * export const MyApiContract = defineApi("MyApi", () => ({
+ *     list: {
+ *         success: IsArray(IsItem),
+ *         errors: [NOT_AUTHORIZED, SERVER_ERROR]
+ *     },
+ *     create: {
+ *         input: IsCreateRequest,
+ *         success: IsItem,
+ *         errors: [NOT_AUTHORIZED, VALIDATION_ERROR, SERVER_ERROR]
+ *     }
+ * }))
+ *
+ * export const MyApi = httpApi(MyApiContract)
+ *     .pathPrefix("api/items")
+ *     .use(AuthMiddleware)
+ *     .routes({
+ *         list: GGRpc.GET("list"),
+ *         create: GGRpc.POST("create")
+ *     })
+ */
+export function httpSchema<TContract extends GGContractApiDefinition>(
+    contract: GGContractClass<TContract>
+): GGHttpSchemaBuilder<TContract> {
+    return new GGHttpSchemaBuilder(contract)
+}
+
+class GGHttpSchemaBuilder<TContract extends GGContractApiDefinition, TContext = undefined> {
+
+    private readonly _contract: GGContractClass<TContract>
+    private _pathPrefix: string = ""
+    private _middlewares: GGHttpTransportMiddleware[] = []
+
+    constructor(contract: GGContractClass<TContract>) {
+        this._contract = contract;
+    }
+
+    pathPrefix(prefix: string): this {
+        this._pathPrefix = prefix
+        return this
+    }
+
+    use<M extends GGHttpTransportMiddleware>(middleware: M): GGHttpSchemaBuilder<TContract, TContext | M> {
+        this._middlewares.push(middleware)
+        return this as unknown as GGHttpSchemaBuilder<TContract, TContext | M>
+    }
+
+    useHeader<Input>(contextKey: GGContextKey<Input>): GGHttpSchemaBuilder<TContract, TContext | Input> {
+        const codec = contextKey.getCodec("http");
+        if (!codec) {
+            throw new Error(`Context key '${contextKey.name}' does not have an 'http-header' codec registered.`);
+        }
+
+        const middleware: GGHttpTransportMiddleware = {
+            updateRequest(req: GGHttpRequest) {
+                // Client-side: context -> headers
+                const contextValue = contextKey.get();
+                if (contextValue !== undefined) {
+                    const result = codec.decode(contextValue);
+                    if (result.success) {
+                        Object.assign(req.headers, result.value);
+                    }
+                } else {
+                    // Clear any default headers by decoding an empty context
+                    const emptyResult = codec.decode({} as Input);
+                    if (emptyResult.success) {
+                        for (const key of Object.keys(emptyResult.value as object)) {
+                            delete req.headers[key];
+                        }
+                    }
+                }
+            },
+            parseRequest(req: http.IncomingMessage) {
+                // Server-side: headers -> context
+                const headers = req.headers as Record<string, string>;
+                const result = codec.encode(headers);
+                if (result.success) {
+                    contextKey.set(result.value);
+                }
+            }
+        };
+
+        this._middlewares.push(middleware);
+        return this as unknown as GGHttpSchemaBuilder<TContract, TContext | Input>;
+    }
+
+    routes(mapping: { [K in keyof TContract]: GGHttpCodec }): GGHttpSchema<TContract, TContext> {
+        return new GGHttpSchema(this._pathPrefix, this._contract, mapping, this._middlewares)
+    }
+}

package/src/server/GGHttp.ts

@@ -0,0 +1,27 @@
+import {GGHttpSchema} from "../schema/GGHttpSchema";
+import {GGContractApiDefinition, GGContractImplementation} from "@grest-ts/schema";
+import {GGHttpServerMiddleware} from "./GGHttpSchema.startServer";
+import {GGHttpServer} from "./GGHttpServer";
+
+export class GGHttp<TContext = undefined> {
+
+    private readonly httpServer: GGHttpServer
+    private readonly middlewares: GGHttpServerMiddleware[] = [];
+
+    constructor(httpServer: GGHttpServer) {
+        this.httpServer = httpServer;
+    }
+
+    public use<M extends GGHttpServerMiddleware>(middleware: M): GGHttp<TContext | M> {
+        this.middlewares.push(middleware);
+        return this as any;
+    }
+
+    public http<TContract extends GGContractApiDefinition, TSchemaContext>(
+        schema: GGHttpSchema<TContract, TSchemaContext>,
+        implementation: GGContractImplementation<TContract>
+    ): this {
+        schema.register(implementation, {http: this.httpServer, middlewares: this.middlewares});
+        return this as any;
+    }
+}

package/src/server/GGHttpMetrics.ts

@@ -0,0 +1,31 @@
+import {GGCounterKey, GGHistogramKey, GGMetrics} from "@grest-ts/metrics";
+import {EXISTS, FORBIDDEN, NOT_AUTHORIZED, NOT_FOUND, OK, ROUTE_NOT_FOUND, SERVER_ERROR, VALIDATION_ERROR} from "@grest-ts/schema";
+
+/**
+ * Result type for HTTP operations.
+ * Known types listed for documentation, but accepts any string for custom error types.
+ */
+type ResultType =
+    | typeof OK.TYPE
+    | typeof VALIDATION_ERROR.TYPE
+    | typeof NOT_AUTHORIZED.TYPE
+    | typeof FORBIDDEN.TYPE
+    | typeof NOT_FOUND.TYPE
+    | typeof ROUTE_NOT_FOUND.TYPE
+    | typeof EXISTS.TYPE
+    | typeof SERVER_ERROR.TYPE
+    | string;
+
+export const GGHttpMetrics = GGMetrics.define('/http/', () => ({
+    requests: new GGCounterKey<{ api: string, method: string, path: string, result: ResultType }>('requests_total', {
+        help: 'Total HTTP requests after contract validation',
+        labelNames: ['api', 'method', 'path', 'result'],
+        groupBy: {labels: ["api", "method"], template: "{api}.{method}"}
+    }),
+    requestDuration: new GGHistogramKey<{ api: string, method: string, path: string }>('request_duration_ms', {
+        help: 'HTTP request duration in milliseconds',
+        labelNames: ['api', 'method', 'path'],
+        buckets: [5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000],
+        groupBy: {labels: ["api", "method"], template: "{api}.{method}"}
+    }),
+}));