Open History to see the last commit
1/**
2 * Service for fetching OpenAPI specifications from URLs or the filesystem.
3 *
4 * @since 4.0.0
5 */
6import * as Context from "effect/Context"
7import * as Data from "effect/Data"
8import * as Effect from "effect/Effect"
9import * as FileSystem from "effect/FileSystem"
10import * as HttpClient from "effect/http/HttpClient"
11import * as Layer from "effect/Layer"
12import * as Match from "effect/Match"
13import * as Zlib from "node:zlib"
14import * as Yaml from "yaml"
15import type { SpecSource } from "./Config.ts"
16
17/**
18 * Error when fetching a spec fails.
19 *
20 * **Example** (Creating a spec fetch error)
21 *
22 * ```ts import.meta.vitest
23 * import * as SpecFetcher from "@effect/ai-codegen/SpecFetcher"
24 *
25 * const error = new SpecFetcher.SpecFetchError({
26 * provider: "openai",
27 * source: "https://example.com/openapi.json",
28 * cause: new Error("Network error")
29 * })
30 *
31 * error._tag // => "SpecFetchError"
32 * error.provider // => "openai"
33 * ```
34 *
35 * @category errors
36 * @since 4.0.0
37 */
38export class SpecFetchError extends Data.TaggedError("SpecFetchError")<{
39 readonly provider: string
40 readonly source: string
41 readonly cause: unknown
42}> {}
43
44/**
45 * Service for fetching OpenAPI specifications.
46 *
47 * @category services
48 * @since 4.0.0
49 */
50export interface SpecFetcher {
51 readonly fetch: (
52 source: SpecSource,
53 provider: string
54 ) => Effect.Effect<unknown, SpecFetchError>
55}
56
57/**
58 * Service tag for fetching OpenAPI specifications from configured sources.
59 *
60 * @category services
61 * @since 4.0.0
62 */
63export const SpecFetcher: Context.Service<SpecFetcher, SpecFetcher> = Context.Service(
64 "@effect/ai-codegen/SpecFetcher"
65)
66
67/**
68 * Layer providing the SpecFetcher service.
69 *
70 * @category layers
71 * @since 4.0.0
72 */
73export const layer: Layer.Layer<
74 SpecFetcher,
75 never,
76 FileSystem.FileSystem | HttpClient.HttpClient
77> = Effect.gen(function*() {
78 const fs = yield* FileSystem.FileSystem
79 const httpClient = HttpClient.filterStatusOk(yield* HttpClient.HttpClient)
80
81 const fetchFromFile = Effect.fn("fetchFromFile")(function*(
82 path: string,
83 provider: string
84 ) {
85 return yield* fs.readFile(path).pipe(
86 Effect.mapError((cause) => new SpecFetchError({ provider, source: path, cause }))
87 )
88 })
89
90 const fetchFromUrl = Effect.fn("fetchFromUrl")(function*(
91 url: string,
92 provider: string
93 ) {
94 return yield* httpClient.get(url).pipe(
95 Effect.flatMap((response) => response.arrayBuffer),
96 Effect.map((buffer) => new Uint8Array(buffer)),
97 Effect.mapError((cause) => new SpecFetchError({ provider, source: url, cause }))
98 )
99 })
100
101 const parseSpec = (content: Uint8Array, source: string, provider: string) =>
102 Effect.try({
103 try: () => {
104 // Gzipped specs are parsed by the extension that precedes `.gz`
105 const isGzip = source.endsWith(".gz")
106 const path = isGzip ? source.slice(0, -".gz".length) : source
107 const text = new TextDecoder().decode(isGzip ? Zlib.gunzipSync(content) : content)
108 const isYaml = path.endsWith(".yaml") || path.endsWith(".yml")
109 return isYaml ? Yaml.parse(text) : JSON.parse(text)
110 },
111 catch: (cause) => new SpecFetchError({ provider, source, cause })
112 })
113
114 const fetch = Effect.fn("fetch")(function*(
115 source: SpecSource,
116 provider: string
117 ) {
118 const content = yield* Match.value(source).pipe(
119 Match.tag("File", ({ path }) => fetchFromFile(path, provider)),
120 Match.tag("Url", ({ url }) => fetchFromUrl(url, provider)),
121 Match.exhaustive
122 )
123
124 const sourceString = source._tag === "Url" ? source.url : source.path
125 return yield* parseSpec(content, sourceString, provider)
126 })
127
128 return { fetch }
129}).pipe(Layer.effect(SpecFetcher))