@redocly/cli 2.47.0 → 2.48.0

package/lib/eject-assets/generators/go/operations.ts

@@ -0,0 +1,296 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "go" generator.
+// This file is yours: edit freely; the generated client stays machine-owned and is
+// rebuilt by `redocly generate-client`. Newer generator versions merge in with
+// `redocly eject-generator go --update`.
+// The `operations` stage: one typed request method per operation, plus the
+// argument and envelope-header planning it shares with the pagination wrappers.
+
+import {
+  type ApiModel,
+  type DateType,
+  headerCoerceType,
+  isMultipartBody,
+  jsonSuccessSchema,
+  type OperationModel,
+  type ParamModel,
+  sseResponse,
+  uniqueIdentifiers,
+} from '@redocly/client-generator';
+import { exported, type GoPrinter } from '@redocly/client-generator/printers/go';
+
+import { GO, naming } from './naming.ts';
+import { goType } from './types.ts';
+
+/** A query-value expression formatted to string for url.Values. */
+export function goQueryFormat(expr: string, type: string): string {
+  if (type === 'string') return expr;
+  // Dates serialize in their wire layout, not Go's default String(). A dereferenced
+  // pointer needs parentheses: `*p.Format(…)` would deref Format's result.
+  const receiver = expr.startsWith('*') ? `(${expr})` : expr;
+  if (type === 'time.Time') return `${receiver}.Format(time.RFC3339)`;
+  if (type === 'Date') return `${receiver}.Format("2006-01-02")`;
+  if (type === 'int64') return `strconv.FormatInt(${expr}, 10)`;
+  if (type === 'float64') return `strconv.FormatFloat(${expr}, 'f', -1, 64)`;
+  if (type === 'bool') return `strconv.FormatBool(${expr})`;
+  return `fmt.Sprint(${expr})`;
+}
+
+/**
+ * The argument names a method declares beside its path parameters: the receiver, the
+ * context, the request body, and the query struct.
+ */
+const METHOD_ARG_SLOTS = ['c', 'ctx', 'body', 'params', 'out', 'op'];
+
+/**
+ * Path parameters as Go arguments, uniquely named. A parameter named after one of the
+ * method's own arguments (or a name a description reuses across locations) moves aside as
+ * `id2` — Go rejects a duplicate parameter, and the wire name is untouched either way.
+ */
+export function pathArguments(
+  op: OperationModel,
+  dateType: DateType
+): Array<{ param: ParamModel; go: string; type: string }> {
+  const names = uniqueIdentifiers(
+    op.pathParams.map((param) => param.name),
+    { style: 'camel', reserved: GO, taken: METHOD_ARG_SLOTS }
+  );
+  return op.pathParams.map((param, index) => ({
+    param,
+    go: names[index],
+    type: goType(param.schema, dateType),
+  }));
+}
+
+/** Declared response headers planned for the `<Op>Headers` struct: field, wire name, coerce helper. */
+function envelopeHeaderPlan(
+  op: OperationModel,
+  model: ApiModel
+): Array<{ field: string; name: string; goType: string; helper: string }> {
+  const used = new Set<string>();
+  return (op.successResponseHeaders ?? []).map((header) => {
+    const base = exported(header.name);
+    let field = base;
+    let suffix = 2;
+    while (used.has(field)) field = `${base}${suffix++}`;
+    used.add(field);
+    const coerce = headerCoerceType(header.schema, model);
+    const mapping = {
+      integer: { goType: '*int64', helper: 'headerInt64' },
+      number: { goType: '*float64', helper: 'headerFloat64' },
+      boolean: { goType: '*bool', helper: 'headerBool' },
+      string: { goType: '*string', helper: 'headerString' },
+    }[coerce];
+    return { field, name: header.name, ...mapping };
+  });
+}
+
+export function writeGoMethod(
+  printer: GoPrinter,
+  op: OperationModel,
+  ident: string,
+  dateType: DateType,
+  model?: ApiModel,
+  envelope = false
+): void {
+  const pathArgs = pathArguments(op, dateType);
+  const hasParams = op.queryParams.length > 0;
+  const success = jsonSuccessSchema(op);
+  const returnType = success === undefined ? undefined : goType(success, dateType);
+  const headerPlan = envelope ? envelopeHeaderPlan(op, model!) : [];
+  if (envelope) {
+    printer.line(
+      `// ${ident}Headers carries the declared response headers of ${ident}WithHeaders (nil when absent or unparsable).`
+    );
+    printer.block(
+      `type ${ident}Headers struct {`,
+      () => {
+        for (const planned of headerPlan) printer.line(`${planned.field} ${planned.goType}`);
+      },
+      '}'
+    );
+    printer.blank();
+  }
+  const args = [
+    'ctx context.Context',
+    ...pathArgs.map(({ go, type }) => `${go} ${type}`),
+    ...(op.requestBody ? [`body ${goType(op.requestBody.schema, dateType)}`] : []),
+    ...(hasParams ? [`params *${ident}Params`] : []),
+  ];
+  const sse = sseResponse(op);
+  const returns = envelope
+    ? returnType === undefined
+      ? `(${ident}Headers, error)`
+      : `(${returnType}, ${ident}Headers, error)`
+    : sse !== undefined
+      ? 'func(yield func(ServerSentEvent, error) bool)'
+      : returnType === undefined
+        ? 'error'
+        : `(${returnType}, error)`;
+  const fail = (errExpr: string) =>
+    envelope
+      ? returnType === undefined
+        ? `return headers, ${errExpr}`
+        : `return out, headers, ${errExpr}`
+      : returnType === undefined
+        ? `return ${errExpr}`
+        : `return out, ${errExpr}`;
+  const funcName = envelope ? `${ident}WithHeaders` : ident;
+  printer.doc(
+    funcName,
+    envelope ? `Like ${ident}, also returning the declared response headers.` : op.summary
+  );
+  printer.block(
+    `func (c *Client) ${funcName}(${args.join(', ')}) ${returns} {`,
+    () => {
+      if (sse === undefined && returnType !== undefined) printer.line(`var out ${returnType}`);
+      if (envelope) printer.line(`var headers ${ident}Headers`);
+      printer.line(`op := operations[${naming.string(op.specName ?? op.name)}]`);
+      printer.line('authHeaders, query := resolveAuth(op.Security, c.config.Auth)');
+      if (hasParams) {
+        printer.block(
+          'if params != nil {',
+          () => {
+            for (const param of op.queryParams) {
+              const field = exported(param.name);
+              printer.block(
+                `if params.${field} != nil {`,
+                () => {
+                  // An array repeats the key per element (OpenAPI `form` + `explode`, the
+                  // default — and what the TS runtime sends). `fmt.Sprint` of a slice
+                  // would put `[a b]` on the wire as one value.
+                  if (param.schema.kind === 'array') {
+                    const elementType = goType(param.schema.items, dateType);
+                    printer.block(
+                      `for _, item := range *params.${field} {`,
+                      () => {
+                        printer.line(
+                          `query.Add(${naming.string(param.name)}, ${goQueryFormat('item', elementType)})`
+                        );
+                      },
+                      '}'
+                    );
+                  } else {
+                    printer.line(
+                      `query.Set(${naming.string(param.name)}, ${goQueryFormat(`*params.${field}`, goType(param.schema, dateType))})`
+                    );
+                  }
+                },
+                '}'
+              );
+            }
+          },
+          '}'
+        );
+      }
+      const pathDict = pathArgs
+        .map(({ param, go, type }) => `${naming.string(param.name)}: ${goQueryFormat(go, type)}`)
+        .join(', ');
+      printer.line(
+        `requestURL := buildURL(c.config.ServerURL, op.Path, map[string]string{${pathDict}})`
+      );
+      if (sse !== undefined) {
+        printer.block(
+          'open := func(extraHeaders map[string]string) (*http.Response, error) {',
+          () => {
+            printer.line('merged := map[string]string{}');
+            printer.block(
+              'for key, value := range authHeaders {',
+              () => {
+                printer.line('merged[key] = value');
+              },
+              '}'
+            );
+            printer.block(
+              'for key, value := range extraHeaders {',
+              () => {
+                printer.line('merged[key] = value');
+              },
+              '}'
+            );
+            printer.line(
+              'return send(ctx, &c.config, requestSpec{OperationID: op.ID, Method: op.Method, URL: requestURL, Headers: merged, Query: query})'
+            );
+          },
+          '}'
+        );
+        printer.line(
+          `return iterSSE(open, ${sse.schema !== undefined && sse.schema.kind !== 'unknown'})`
+        );
+        return;
+      }
+      const specFields = [
+        'OperationID: op.ID',
+        'Method: op.Method',
+        'URL: requestURL',
+        'Headers: authHeaders',
+        'Query: query',
+      ];
+      if (op.requestBody && isMultipartBody(op)) {
+        printer.line('contentType, reader, err := toMultipart(body)');
+        printer.block(
+          'if err != nil {',
+          () => {
+            printer.line(fail('err'));
+          },
+          '}'
+        );
+        specFields.push('Body: reader');
+        specFields.push('ContentType: contentType');
+      } else if (op.requestBody) {
+        printer.line('payload, err := json.Marshal(body)');
+        printer.block(
+          'if err != nil {',
+          () => {
+            printer.line(fail('err'));
+          },
+          '}'
+        );
+        specFields.push('Body: bytes.NewReader(payload)');
+        specFields.push(`ContentType: ${naming.string(op.requestBody.contentType)}`);
+      }
+      printer.line(`resp, err := send(ctx, &c.config, requestSpec{${specFields.join(', ')}})`);
+      printer.block(
+        'if err != nil {',
+        () => {
+          printer.line(fail('err'));
+        },
+        '}'
+      );
+      printer.block(
+        'if resp.StatusCode >= 400 {',
+        () => {
+          printer.line(fail('apiErrorFrom(resp, requestURL)'));
+        },
+        '}'
+      );
+      if (envelope) {
+        printer.block(
+          `if err := decodeJSON(resp, ${returnType === undefined ? 'nil' : '&out'}); err != nil {`,
+          () => {
+            printer.line(fail('err'));
+          },
+          '}'
+        );
+        for (const planned of headerPlan) {
+          printer.line(
+            `headers.${planned.field} = ${planned.helper}(resp.Header, ${naming.string(planned.name)})`
+          );
+        }
+        printer.line(returnType === undefined ? 'return headers, nil' : 'return out, headers, nil');
+      } else if (returnType === undefined) {
+        printer.line('return decodeJSON(resp, nil)');
+      } else {
+        printer.block(
+          'if err := decodeJSON(resp, &out); err != nil {',
+          () => {
+            printer.line('return out, err');
+          },
+          '}'
+        );
+        printer.line('return out, nil');
+      }
+    },
+    '}'
+  );
+  printer.blank();
+}

package/lib/eject-assets/generators/go/pagination.ts

@@ -0,0 +1,194 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "go" generator.
+// This file is yours: edit freely; the generated client stays machine-owned and is
+// rebuilt by `redocly generate-client`. Newer generator versions merge in with
+// `redocly eject-generator go --update`.
+// The `pagination` stage: the `<Op>Pages` / `<Op>Items` yield-func iterators.
+
+import { type DateType, type OperationModel } from '@redocly/client-generator';
+import { exported, type GoPrinter } from '@redocly/client-generator/printers/go';
+
+import { naming } from './naming.ts';
+import { goQueryFormat, pathArguments } from './operations.ts';
+import { goType } from './types.ts';
+
+/** `<Op>Pages` / `<Op>Items` iterators over the runtime's `iterPages`, hydrated via `reencode`. */
+export function writeGoPaginationWrappers(
+  printer: GoPrinter,
+  op: OperationModel,
+  ident: string,
+  dateType: DateType,
+  pageType: string,
+  itemType: string
+): void {
+  const pathArgs = pathArguments(op, dateType);
+  const hasParams = op.queryParams.length > 0;
+  const args = [
+    'ctx context.Context',
+    ...pathArgs.map(({ go, type }) => `${go} ${type}`),
+    ...(hasParams ? [`params *${ident}Params`] : []),
+  ].join(', ');
+
+  const writeCallClosure = () => {
+    printer.line(`op := operations[${naming.string(op.specName ?? op.name)}]`);
+    printer.line('base := url.Values{}');
+    if (hasParams) {
+      printer.block(
+        'if params != nil {',
+        () => {
+          for (const param of op.queryParams) {
+            const field = exported(param.name);
+            printer.block(
+              `if params.${field} != nil {`,
+              () => {
+                printer.line(
+                  `base.Set(${naming.string(param.name)}, ${goQueryFormat(`*params.${field}`, goType(param.schema, dateType))})`
+                );
+              },
+              '}'
+            );
+          }
+        },
+        '}'
+      );
+    }
+    printer.block(
+      'call := func(pageParams url.Values) (any, *http.Response, error) {',
+      () => {
+        printer.line('authHeaders, query := resolveAuth(op.Security, c.config.Auth)');
+        printer.block(
+          'for key, values := range pageParams {',
+          () => {
+            printer.block(
+              'for _, value := range values {',
+              () => {
+                printer.line('query.Set(key, value)');
+              },
+              '}'
+            );
+          },
+          '}'
+        );
+        const pathDict = pathArgs
+          .map(({ param, go, type }) => `${naming.string(param.name)}: ${goQueryFormat(go, type)}`)
+          .join(', ');
+        printer.line(
+          `requestURL := buildURL(c.config.ServerURL, op.Path, map[string]string{${pathDict}})`
+        );
+        printer.line(
+          'resp, err := send(ctx, &c.config, requestSpec{OperationID: op.ID, Method: op.Method, URL: requestURL, Headers: authHeaders, Query: query})'
+        );
+        printer.block(
+          'if err != nil {',
+          () => {
+            printer.line('return nil, nil, err');
+          },
+          '}'
+        );
+        printer.block(
+          'if resp.StatusCode >= 400 {',
+          () => {
+            printer.line('return nil, resp, apiErrorFrom(resp, requestURL)');
+          },
+          '}'
+        );
+        printer.line('var raw any');
+        printer.block(
+          'if err := decodeJSON(resp, &raw); err != nil {',
+          () => {
+            printer.line('return nil, resp, err');
+          },
+          '}'
+        );
+        printer.line('return raw, resp, nil');
+      },
+      '}'
+    );
+    printer.line('pages := iterPages(call, *op.Pagination, base)');
+  };
+
+  printer.line(
+    `// ${ident}Pages iterates ${ident} response pages; use with \`for page, err := range\`.`
+  );
+  printer.block(
+    `func (c *Client) ${ident}Pages(${args}) func(yield func(${pageType}, error) bool) {`,
+    () => {
+      writeCallClosure();
+      printer.block(
+        `return func(yield func(${pageType}, error) bool) {`,
+        () => {
+          printer.block(
+            'pages(func(raw any, err error) bool {',
+            () => {
+              printer.line(`var page ${pageType}`);
+              printer.block(
+                'if err == nil {',
+                () => {
+                  printer.line('err = reencode(raw, &page)');
+                },
+                '}'
+              );
+              printer.line('return yield(page, err)');
+            },
+            '})'
+          );
+        },
+        '}'
+      );
+    },
+    '}'
+  );
+  printer.blank();
+
+  printer.line(`// ${ident}Items iterates the items of every ${ident} page.`);
+  printer.block(
+    `func (c *Client) ${ident}Items(${args}) func(yield func(${itemType}, error) bool) {`,
+    () => {
+      writeCallClosure();
+      printer.block(
+        `return func(yield func(${itemType}, error) bool) {`,
+        () => {
+          printer.block(
+            'pages(func(raw any, err error) bool {',
+            () => {
+              printer.block(
+                'if err != nil {',
+                () => {
+                  printer.line(`var zero ${itemType}`);
+                  printer.line('return yield(zero, err)');
+                },
+                '}'
+              );
+              printer.line('pageItems, _ := resolvePointer(raw, op.Pagination.Items).([]any)');
+              printer.block(
+                'for _, item := range pageItems {',
+                () => {
+                  printer.line(`var typed ${itemType}`);
+                  printer.block(
+                    'if err := reencode(item, &typed); err != nil {',
+                    () => {
+                      printer.line('return yield(typed, err)');
+                    },
+                    '}'
+                  );
+                  printer.block(
+                    'if !yield(typed, nil) {',
+                    () => {
+                      printer.line('return false');
+                    },
+                    '}'
+                  );
+                },
+                '}'
+              );
+              printer.line('return true');
+            },
+            '})'
+          );
+        },
+        '}'
+      );
+    },
+    '}'
+  );
+  printer.blank();
+}

package/lib/eject-assets/generators/go/types.ts

@@ -0,0 +1,60 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "go" generator.
+// This file is yours: edit freely; the generated client stays machine-owned and is
+// rebuilt by `redocly generate-client`. Newer generator versions merge in with
+// `redocly eject-generator go --update`.
+// The `types` stage: the Go type annotation for a schema.
+
+import {
+  type DateType,
+  isNullable,
+  type SchemaModel,
+  unwrapNullable,
+} from '@redocly/client-generator';
+import { exported } from '@redocly/client-generator/printers/go';
+
+/** The Go type for a schema; `required=false` optionals become pointers at the field site. */
+export function goType(schema: SchemaModel, dateType: DateType = 'string'): string {
+  if (isNullable(schema)) {
+    const inner = goType(unwrapNullable(schema), dateType);
+    return inner.startsWith('*') || inner === 'any' ? inner : `*${inner}`;
+  }
+  switch (schema.kind) {
+    case 'scalar':
+      // Under `dateType: Date`, a date-time is a time.Time (encoding/json handles
+      // RFC 3339 natively) and a bare date is the runtime's `Date` wrapper.
+      if (dateType === 'Date' && schema.scalar === 'string') {
+        if (schema.metadata?.format === 'date-time') return 'time.Time';
+        if (schema.metadata?.format === 'date') return 'Date';
+      }
+      return { string: 'string', integer: 'int64', number: 'float64', boolean: 'bool' }[
+        schema.scalar
+      ];
+    case 'array':
+      return `[]${goType(schema.items, dateType)}`;
+    case 'record':
+      return `map[string]${goType(schema.value, dateType)}`;
+    case 'ref':
+      return exported(schema.name);
+    case 'literal':
+      return typeof schema.value === 'string'
+        ? 'string'
+        : typeof schema.value === 'boolean'
+          ? 'bool'
+          : 'float64';
+    case 'enum':
+      // Anonymous (inline) enums keep the wire scalar; only NAMED enums get types.
+      return { string: 'string', integer: 'int64', number: 'float64', boolean: 'bool' }[
+        schema.scalar
+      ];
+    case 'omit':
+      // Go has no Omit; the base struct is the honest annotation (readOnly
+      // fields are server-managed and simply omitted from requests).
+      return exported(schema.base);
+    case 'union':
+    case 'null':
+    case 'object':
+    case 'intersection':
+    case 'unknown':
+      return 'any';
+  }
+}