@planet-matrix/mobius-model 0.6.0 → 0.9.0

package/src/http/api-adapter/api-host-node-http.ts

@@ -0,0 +1,156 @@
+import type { IncomingMessage, Server, ServerResponse } from "node:http"
+import { createServer } from "node:http"
+import { networkInterfaces } from "node:os"
+
+import type { ApiCoreHandler, ApiHostStartResult, ApiHostOptions } from "../api/api-host.ts"
+import { ApiHost } from "../api/api-host.ts"
+
+import { ApiCoreNodeHttp } from "./api-core-node-http.ts"
+
+const internalGetListeningPort = (server: Server): number => {
+  const address = server.address()
+
+  if (address === null) {
+    throw new Error("Server is not running.")
+  }
+
+  if (typeof address === "string") {
+    throw new TypeError("HTTP server is not listening on a TCP port.")
+  }
+
+  return address.port
+}
+const internalFormatHttpHost = (address: string): string => {
+  const normalizedAddress = address.replaceAll("%", "%25")
+
+  if (normalizedAddress.includes(":")) {
+    return `[${normalizedAddress}]`
+  }
+
+  return normalizedAddress
+}
+const internalBuildHttpUrlList = (port: number): string[] => {
+  const urlSet = new Set<string>([
+    `http://127.0.0.1:${port}`,
+    `http://localhost:${port}`,
+    `http://[::1]:${port}`,
+  ])
+
+  for (const networkInterfaceInfo of Object.values(networkInterfaces()).flat()) {
+    if (
+      networkInterfaceInfo === undefined
+      || networkInterfaceInfo.address.length === 0
+      || networkInterfaceInfo.internal === true
+      || networkInterfaceInfo.address === "0.0.0.0"
+      || networkInterfaceInfo.address === "::"
+    ) {
+      continue
+    }
+
+    const address = internalFormatHttpHost(networkInterfaceInfo.address)
+    urlSet.add(`http://${address}:${port}`)
+  }
+
+  return [...urlSet]
+}
+
+export interface ApiHostNodeHttpOptions extends ApiHostOptions {
+}
+export class ApiHostNodeHttp extends ApiHost<Server> {
+  protected apiCoreHandler: ApiCoreHandler | undefined
+
+  constructor(options: ApiHostNodeHttpOptions) {
+    super(options)
+
+    this.apiCoreHandler = undefined
+  }
+
+  attachApiCoreHandler(apiCoreHandler: ApiCoreHandler): void {
+    this.apiCoreHandler = apiCoreHandler
+  }
+
+  async start(): Promise<ApiHostStartResult> {
+    if (this.server !== undefined) {
+      throw new Error("Server is already running.")
+    }
+
+    const server = createServer((request, response) => {
+      void this.handleRequest(request, response)
+    })
+
+    const result = await new Promise<ApiHostStartResult>((resolve, reject) => {
+      const handleError = (error: Error): void => {
+        server.off("listening", handleListening)
+        this.server = undefined
+        reject(error)
+      }
+
+      const handleListening = (): void => {
+        server.off("error", handleError)
+        this.server = server
+
+        server.once("close", () => {
+          if (this.server === server) {
+            this.server = undefined
+          }
+        })
+
+        const port = internalGetListeningPort(server)
+        resolve({
+          urlList: internalBuildHttpUrlList(port),
+        })
+      }
+
+      server.once("error", handleError)
+      server.once("listening", handleListening)
+      server.listen(this.options.port)
+    })
+
+    return result
+  }
+
+  async close(): Promise<void> {
+    if (this.isRunning() === false) {
+      return
+    }
+
+    const server = this.safeGetServer()
+
+    await new Promise<void>((resolve, reject) => {
+      server.close((error) => {
+        if (error !== undefined) {
+          reject(error)
+          return
+        }
+
+        resolve()
+      })
+    })
+  }
+
+  protected async handleRequest(
+    request: IncomingMessage,
+    response: ServerResponse<IncomingMessage>,
+  ): Promise<void> {
+    const apiCore = new ApiCoreNodeHttp({ request, response })
+    const apiCoreHandler = this.apiCoreHandler
+
+    if (apiCoreHandler === undefined) {
+      this.logger.error("Request handling skipped because no ApiCore handler is attached.")
+      await apiCore.error()
+      return
+    }
+
+    try {
+      await apiCoreHandler(apiCore)
+    }
+    catch (exception) {
+      this.logger.error(`Request handling failed, exception: ${String(exception)}`)
+      await apiCore.error()
+    }
+  }
+}
+
+export const createApiHostNodeHttp = (options: ApiHostNodeHttpOptions): ApiHostNodeHttp => {
+  return new ApiHostNodeHttp(options)
+}

package/src/http/api-adapter/api-result-arktype.ts

@@ -0,0 +1,297 @@
+import type { Type } from "arktype"
+import { type } from "arktype"
+
+import { generateUuidV4 } from "#Source/identifier/uuid.ts"
+
+import type { ApiCore, ApiCoreStream } from "../api/api-core.ts"
+import type { SuccessResultOptions, ErrorResultOptions } from "../api/api-result.ts"
+import type { ApiHandlerContext } from "../api/api-handler.ts"
+
+import { SuccessResult, ErrorResult } from "../api/api-result.ts"
+
+export interface JsonSuccessResultOptions<Data> extends SuccessResultOptions<Data> {
+  data: Data
+}
+export class JsonSuccessResult<Data> extends SuccessResult<Data> {
+  protected declare options: JsonSuccessResultOptions<Data>
+
+  constructor(options: JsonSuccessResultOptions<Data>) {
+    super(options)
+    this.logger.setDefaultName("JsonSuccessResult")
+  }
+
+  async handle(apiCore: ApiCore): Promise<void> {
+    const { data } = this.options
+
+    this.logger.log(`send, ${JSON.stringify(data, null, 2)}`)
+    await apiCore.json(data)
+    this.logger.log(`end`)
+  }
+}
+
+export interface CommonSuccessJson<Data> {
+  status: "success"
+  data: Data
+}
+export interface CommonJsonSuccessResultOptions<Data> extends
+  Omit<JsonSuccessResultOptions<CommonSuccessJson<Data>>, "data"> {
+  data: Data
+}
+export class CommonJsonSuccessResult<Data>
+  extends JsonSuccessResult<CommonSuccessJson<Data>> {
+  protected declare options: JsonSuccessResultOptions<CommonSuccessJson<Data>>
+
+  constructor(options: CommonJsonSuccessResultOptions<Data>) {
+    super({
+      ...options,
+      data: {
+        status: "success",
+        data: options.data,
+      },
+    })
+    this.logger.setDefaultName("CommonJsonSuccessResult")
+  }
+}
+export const commonJsonSuccessResult = <Data>(
+  options: CommonJsonSuccessResultOptions<Data>
+): CommonJsonSuccessResult<Data> => {
+  return new CommonJsonSuccessResult<Data>(options)
+}
+
+export type CommonJsonSuccessResultSchema<Data> = Type<{
+  status: "success"
+  data: Data
+}>
+export type GetDataSchemaFromCommonJsonSuccessResultSchema<Schema extends Type>
+  = Schema extends CommonJsonSuccessResultSchema<infer Data> ? Type<Data> : never
+export type GetDataFromCommonJsonSuccessResultSchema<Schema extends Type>
+  = Schema extends CommonJsonSuccessResultSchema<infer Data> ? Data : never
+export const commonJsonSuccessResultSchema = <Data extends Record<string, unknown>>(
+  dataSchema: Type<Data>
+): CommonJsonSuccessResultSchema<Data> => {
+  // arktype's instantiated object schema is compatible here but
+  // not assignable through its generic facade
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+  return type({
+    status: "'success'",
+    data: dataSchema,
+  }) as CommonJsonSuccessResultSchema<Data>
+}
+
+export type StreamWrite = (chunk: Buffer | string, encoding: BufferEncoding) => void | Promise<void>
+export type StreamEnd = () => void | Promise<void>
+export interface StreamSuccessResultOptions extends SuccessResultOptions<unknown> {
+  writeHandler: (write: StreamWrite) => Promise<void>
+}
+export class StreamSuccessResult extends SuccessResult<unknown> {
+  protected declare options: StreamSuccessResultOptions
+
+  protected streamId: string
+
+  constructor(options: StreamSuccessResultOptions) {
+    super(options)
+    this.logger.setDefaultName("StreamSuccessResult")
+    this.streamId = generateUuidV4()
+  }
+
+  async handle(apiCore: ApiCore): Promise<void> {
+    const apiCoreStream = await apiCore.stream()
+
+    const write = this.wrapWrite(apiCoreStream)
+    await this.options.writeHandler(write)
+    const end = this.wrapEnd(apiCoreStream)
+    await end()
+  }
+
+  /**
+   * 把 write 方法包装一下，以达到注入日志等目的。
+   */
+  protected wrapWrite(apiCoreStream: ApiCoreStream): StreamWrite {
+    return async (chunk, encoding): Promise<void> => {
+      this.logger.log(`send, id: ${this.streamId}, data: ${String(chunk)}`)
+      await apiCoreStream.write(chunk, encoding)
+    }
+  }
+
+  /**
+   * 把 end 方法包装一下，以达到注入日志等目的。
+   */
+  protected wrapEnd(apiCoreStream: ApiCoreStream): StreamEnd {
+    const end = async (): Promise<void> => {
+      this.logger.log(`end, id: ${this.streamId}`)
+      await apiCoreStream.end()
+    }
+    return end
+  }
+}
+
+export type CustomHandler = (apiCore: ApiCore) => Promise<void>
+export interface CustomSuccessResultOptions extends SuccessResultOptions<unknown> {
+  customHandler: CustomHandler
+}
+export class CustomSuccessResult extends SuccessResult<unknown> {
+  protected declare options: CustomSuccessResultOptions
+
+  constructor(options: CustomSuccessResultOptions) {
+    super(options)
+    this.logger.setDefaultName("CustomSuccessResult")
+  }
+
+  async handle(apiCore: ApiCore): Promise<void> {
+    this.logger.log(`send`)
+    await this.options.customHandler(apiCore)
+    this.logger.log(`end`)
+  }
+}
+
+// ======================
+
+export interface JsonErrorResultOptions<Data> extends ErrorResultOptions<Data> {
+  data: Data
+}
+export class JsonErrorResult<Data> extends ErrorResult<Data> {
+  protected declare options: JsonErrorResultOptions<Data>
+
+  constructor(options: JsonErrorResultOptions<Data>) {
+    super(options)
+    this.logger.setDefaultName("JsonErrorResult")
+  }
+
+  async handle(apiCore: ApiCore): Promise<void> {
+    const { data } = this.options
+
+    this.logger.log(`send, ${JSON.stringify(data, null, 2)}`)
+    await apiCore.json(data)
+    this.logger.log(`end`)
+  }
+}
+
+export interface CommonErrorJsonData<Reason extends string> {
+  reason: Reason
+  reasonDetail?: string | undefined
+}
+export interface CommonErrorJson<Reason extends string> {
+  status: "error"
+  data: CommonErrorJsonData<Reason>
+}
+export interface CommonJsonErrorResultOptions<Reason extends string>
+  extends Omit<JsonErrorResultOptions<CommonErrorJson<Reason>>, "data">,
+  CommonErrorJsonData<Reason> {
+}
+export class CommonJsonErrorResult<const Reason extends string>
+  extends JsonErrorResult<CommonErrorJson<Reason>> {
+  protected declare options: JsonErrorResultOptions<CommonErrorJson<Reason>>
+
+  constructor(options: CommonJsonErrorResultOptions<Reason>) {
+    super({
+      ...options,
+      data: {
+        status: "error",
+        data: {
+          reason: options.reason,
+          reasonDetail: options.reasonDetail,
+        },
+      },
+    })
+    this.logger.setDefaultName("CommonJsonErrorResult")
+  }
+}
+export const commonJsonErrorResult = <const Reason extends string>(
+  options: CommonJsonErrorResultOptions<Reason>
+): CommonJsonErrorResult<Reason> => {
+  return new CommonJsonErrorResult<Reason>(options)
+}
+
+export type CommonJsonErrorResultSchema<
+  Data extends {
+    reason: string
+    reasonDetail?: string | undefined
+  }
+> = Type<{
+  status: "error"
+  data: Data & {
+    reasonDetail: string | undefined
+  }
+}>
+export type GetDataSchemaFromCommonJsonErrorResultSchema<Schema extends Type>
+  = Schema extends CommonJsonErrorResultSchema<infer Data> ? Type<Data> : never
+export type GetDataFromCommonJsonErrorResultSchema<Schema extends Type>
+  = Schema extends CommonJsonErrorResultSchema<infer Data> ? Data : never
+export type GetReasonFromCommonJsonErrorResultSchema<Schema extends Type>
+  = Schema extends CommonJsonErrorResultSchema<infer Data>
+  ? Data extends { reason: infer Reason } ? Reason : never
+  : never
+export const commonJsonErrorResultSchema = <
+  Data extends {
+    reason: string
+    reasonDetail?: string | undefined
+  }
+>(
+  dataSchema: Type<Data>
+): CommonJsonErrorResultSchema<Data> => {
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+  return type({
+    status: "'error'",
+    data: type.and(
+      // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+      dataSchema as Type<{
+        reason: string
+        reasonDetail?: string | undefined
+      }>,
+      {
+        reasonDetail: type.string
+      }
+    ),
+  }) as CommonJsonErrorResultSchema<Data>
+}
+
+// ======================
+
+export type ContextWithResultHandler<
+  Path extends string,
+  Method extends "get" | "post",
+  InputQuerySchema extends Type,
+  InputBodySchema extends Type,
+  OutputSuccessSchema extends Type,
+  OutputErrorSchema extends Type,
+>
+  = ApiHandlerContext<Path, Method, InputQuerySchema, InputBodySchema, OutputSuccessSchema, OutputErrorSchema>
+  & {
+    commonJsonSuccessResult: (
+      options: CommonJsonSuccessResultOptions<GetDataFromCommonJsonSuccessResultSchema<OutputSuccessSchema>>
+    ) => CommonJsonSuccessResult<GetDataFromCommonJsonSuccessResultSchema<OutputSuccessSchema>>
+    commonJsonErrorResult: (
+      options: CommonJsonErrorResultOptions<GetReasonFromCommonJsonErrorResultSchema<OutputErrorSchema>>
+    ) => CommonJsonErrorResult<GetReasonFromCommonJsonErrorResultSchema<OutputErrorSchema>>
+  }
+
+export const withResultHandler = <
+  Path extends string,
+  Method extends "get" | "post",
+  InputQuerySchema extends Type,
+  InputBodySchema extends Type,
+  OutputSuccessSchema extends Type,
+  OutputErrorSchema extends Type,
+>(
+  context: ApiHandlerContext<Path, Method, InputQuerySchema, InputBodySchema, OutputSuccessSchema, OutputErrorSchema>,
+): ContextWithResultHandler<Path, Method, InputQuerySchema, InputBodySchema, OutputSuccessSchema, OutputErrorSchema> => {
+  return {
+    ...context,
+    commonJsonSuccessResult: (
+      options: CommonJsonSuccessResultOptions<GetDataFromCommonJsonSuccessResultSchema<OutputSuccessSchema>>,
+    ) => {
+      return commonJsonSuccessResult({
+        logger: context.logger,
+        ...options,
+      })
+    },
+    commonJsonErrorResult: (
+      options: CommonJsonErrorResultOptions<GetReasonFromCommonJsonErrorResultSchema<OutputErrorSchema>>,
+    ) => {
+      return commonJsonErrorResult<GetReasonFromCommonJsonErrorResultSchema<OutputErrorSchema>>({
+        logger: context.logger,
+        ...options,
+      })
+    },
+  }
+}