@redocly/openapi-core 1.0.0-beta.100

package/src/lint.ts

@@ -0,0 +1,125 @@
+import { BaseResolver, resolveDocument, Document, makeDocumentFromString } from './resolve';
+import {
+  normalizeVisitors,
+} from './visitors';
+import { Oas3_1Types } from './types/oas3_1';
+import { Oas3Types } from './types/oas3';
+import { Oas2Types } from './types/oas2';
+import { NodeType } from './types';
+import { ProblemSeverity, WalkContext, walkDocument } from './walk';
+import { LintConfig, Config, initRules, defaultPlugin, resolvePlugins } from './config';
+import { normalizeTypes } from './types';
+import { releaseAjvInstance } from './rules/ajv';
+import { detectOpenAPI, Oas3RuleSet, OasMajorVersion, OasVersion, openAPIMajor } from './oas-types';
+import { ConfigTypes } from './types/redocly-yaml';
+import { OasSpec } from './rules/common/spec';
+
+
+export async function lint(opts: {
+  ref: string;
+  config: Config;
+  externalRefResolver?: BaseResolver;
+}) {
+  const { ref, externalRefResolver = new BaseResolver(opts.config.resolve) } = opts;
+  const document = (await externalRefResolver.resolveDocument(null, ref, true)) as Document;
+
+  return lintDocument({
+    document,
+    ...opts,
+    externalRefResolver,
+    config: opts.config.lint,
+  });
+}
+
+export async function lintFromString(opts: {
+  source: string;
+  absoluteRef?: string;
+  config: Config;
+  externalRefResolver?: BaseResolver;
+}) {
+  const { source, absoluteRef, externalRefResolver = new BaseResolver(opts.config.resolve) } = opts;
+  const document = makeDocumentFromString(source, absoluteRef || '/');
+
+  return lintDocument({
+    document,
+    ...opts,
+    externalRefResolver,
+    config: opts.config.lint,
+  });
+}
+
+export async function lintDocument(opts: {
+  document: Document;
+  config: LintConfig;
+  customTypes?: Record<string, NodeType>;
+  externalRefResolver: BaseResolver;
+}) {
+  releaseAjvInstance(); // FIXME: preprocessors can modify nodes which are then cached to ajv-instance by absolute path
+
+  const { document, customTypes, externalRefResolver, config } = opts;
+  const oasVersion = detectOpenAPI(document.parsed);
+  const oasMajorVersion = openAPIMajor(oasVersion);
+  const rules = config.getRulesForOasVersion(oasMajorVersion);
+  const types = normalizeTypes(
+    config.extendTypes(
+      customTypes ?? oasMajorVersion === OasMajorVersion.Version3 ? (oasVersion === OasVersion.Version3_1 ? Oas3_1Types : Oas3Types) : Oas2Types,
+      oasVersion,
+    ),
+    config,
+  );
+
+  const ctx: WalkContext = {
+    problems: [],
+    oasVersion: oasVersion,
+    visitorsData: {},
+  };
+
+  const preprocessors = initRules(rules as any, config, 'preprocessors', oasVersion);
+  const regularRules = initRules(rules as Oas3RuleSet[], config, 'rules', oasVersion);
+  const normalizedVisitors = normalizeVisitors([...preprocessors, ...regularRules] as any, types);
+  const resolvedRefMap = await resolveDocument({
+    rootDocument: document,
+    rootType: types.DefinitionRoot,
+    externalRefResolver
+  });
+
+  walkDocument({
+    document,
+    rootType: types.DefinitionRoot,
+    normalizedVisitors,
+    resolvedRefMap,
+    ctx,
+  });
+  return ctx.problems.map((problem) => config.addProblemToIgnore(problem));
+}
+
+export async function lintConfig(opts: {
+  document: Document,
+}) {
+  const { document } = opts;
+
+  const ctx: WalkContext = {
+    problems: [],
+    oasVersion: OasVersion.Version3_0,
+    visitorsData: {},
+  };
+  const plugins = resolvePlugins([defaultPlugin]);
+  const config = new LintConfig({
+    plugins,
+    rules: { spec: 'error' },
+  });
+
+  const types = normalizeTypes(ConfigTypes, config);
+  const rules = [{ severity: 'error' as ProblemSeverity, ruleId: 'spec', visitor: OasSpec({ severity: 'error' }) }];
+  const normalizedVisitors = normalizeVisitors(rules, types);
+
+  walkDocument({
+    document,
+    rootType: types.ConfigRoot,
+    normalizedVisitors,
+    resolvedRefMap: new Map(),
+    ctx,
+  });
+
+  return ctx.problems;
+}

package/src/oas-types.ts

@@ -0,0 +1,62 @@
+import {
+  Oas3Rule,
+  Oas3Preprocessor,
+  Oas2Rule,
+  Oas2Preprocessor,
+} from './visitors';
+
+export type RuleSet<T> = Record<string, T>;
+
+export enum OasVersion {
+  Version2 = 'oas2',
+  Version3_0 = 'oas3_0',
+  Version3_1 = 'oas3_1',
+}
+
+export enum OasMajorVersion {
+  Version2 = 'oas2',
+  Version3 = 'oas3',
+}
+
+export type Oas3RuleSet = Record<string, Oas3Rule>;
+export type Oas2RuleSet = Record<string, Oas2Rule>;
+export type Oas3PreprocessorsSet = Record<string, Oas3Preprocessor>;
+export type Oas2PreprocessorsSet = Record<string, Oas2Preprocessor>;
+export type Oas3DecoratorsSet = Record<string, Oas3Preprocessor>;
+export type Oas2DecoratorsSet = Record<string, Oas2Preprocessor>;
+
+export function detectOpenAPI(root: any): OasVersion {
+  if (typeof root !== 'object') {
+    throw new Error(`Document must be JSON object, got ${typeof root}`);
+  }
+
+  if (!(root.openapi || root.swagger)) {
+    throw new Error('This doesn’t look like an OpenAPI document.\n');
+  }
+
+  if (root.openapi && typeof root.openapi !== 'string') {
+    throw new Error(`Invalid OpenAPI version: should be a string but got "${typeof root.openapi}"`);
+  }
+
+  if (root.openapi && root.openapi.startsWith('3.0')) {
+    return OasVersion.Version3_0;
+  }
+
+  if (root.openapi && root.openapi.startsWith('3.1')) {
+    return OasVersion.Version3_1;
+  }
+
+  if (root.swagger && root.swagger === '2.0') {
+    return OasVersion.Version2;
+  }
+
+  throw new Error(`Unsupported OpenAPI Version: ${root.openapi || root.swagger}`);
+}
+
+export function openAPIMajor(version: OasVersion): OasMajorVersion {
+  if (version === OasVersion.Version2) {
+    return OasMajorVersion.Version2;
+  } else {
+    return OasMajorVersion.Version3;
+  }
+}

package/src/redocly/__tests__/redocly-client.test.ts

@@ -0,0 +1,140 @@
+import { RedoclyClient } from '../index';
+
+jest.mock('node-fetch', () => ({
+  default: jest.fn(() => ({
+    ok: true,
+    json: jest.fn().mockResolvedValue({}),
+  })),
+}));
+
+describe('RedoclyClient', () => {
+  const REDOCLY_DOMAIN_US = 'redocly.com';
+  const REDOCLY_DOMAIN_EU = 'eu.redocly.com';
+  const REDOCLY_AUTHORIZATION_TOKEN = 'redocly-auth-token';
+  const testRedoclyDomain = 'redoclyDomain.com';
+  const testToken = 'test-token';
+
+  afterEach(() => {
+    delete process.env.REDOCLY_DOMAIN;
+  });
+
+  it('should resolve the US domain by default', () => {
+    const client = new RedoclyClient();
+    expect(client.domain).toBe(REDOCLY_DOMAIN_US);
+  });
+
+  it('should resolve domain from RedoclyDomain env', () => {
+    process.env.REDOCLY_DOMAIN = testRedoclyDomain;
+    const client = new RedoclyClient();
+    expect(client.domain).toBe(testRedoclyDomain);
+  });
+
+  it('should resolve a domain by US region', () => {
+    const client = new RedoclyClient('us');
+    expect(client.domain).toBe(REDOCLY_DOMAIN_US);
+  });
+
+  it('should resolve a domain by EU region', () => {
+    const client = new RedoclyClient('eu');
+    expect(client.domain).toBe(REDOCLY_DOMAIN_EU);
+  });
+
+  it('should resolve domain by EU region prioritizing flag over env variable', () => {
+    process.env.REDOCLY_DOMAIN = testRedoclyDomain;
+    const client = new RedoclyClient('eu');
+    expect(client.domain).toBe(REDOCLY_DOMAIN_EU);
+  });
+
+  it('should resolve domain by US region prioritizing flag over env variable', () => {
+    process.env.REDOCLY_DOMAIN = testRedoclyDomain;
+    const client = new RedoclyClient('us');
+    expect(client.domain).toBe(REDOCLY_DOMAIN_US);
+  });
+
+  it('should resolve domain by US region when REDOCLY_DOMAIN consists EU domain', () => {
+    process.env.REDOCLY_DOMAIN = REDOCLY_DOMAIN_EU;
+    const client = new RedoclyClient();
+    expect(client.getRegion()).toBe('eu');
+  });
+
+  it('should resolve all tokens', async () => {
+    let spy = jest.spyOn(RedoclyClient.prototype, 'readCredentialsFile').mockImplementation(() => {
+      return { token: "accessToken", us: "accessToken", eu: "eu-accessToken" };
+    });
+    const client = new RedoclyClient();
+    const tokens = client.getAllTokens();
+    expect(tokens).toStrictEqual([
+      { region: 'us', token: 'accessToken' },
+      { region: 'eu', token: 'eu-accessToken' }
+    ]);
+    spy.mockRestore();
+  });
+
+  it('should resolve valid tokens data', async () => {
+    let spy = jest.spyOn(RedoclyClient.prototype, 'readCredentialsFile').mockImplementation(() => {
+      return { us: "accessToken", eu: "eu-accessToken" }
+    });
+    const client = new RedoclyClient();
+    const tokens = await client.getValidTokens();
+    expect(tokens).toStrictEqual([
+      { region: 'us', token: 'accessToken', valid: true },
+      { region: 'eu', token: 'eu-accessToken', valid: true }
+    ]);
+    spy.mockRestore();
+  });
+
+  it('should not call setAccessTokens by default', () => {
+    let spy = jest.spyOn(RedoclyClient.prototype, 'readCredentialsFile').mockImplementation(() => ({}));
+    jest.spyOn(RedoclyClient.prototype, 'setAccessTokens').mockImplementation();
+    const client = new RedoclyClient();
+    expect(client.setAccessTokens).not.toHaveBeenCalled()
+    spy.mockRestore();
+  });
+
+  it('should set correct accessTokens - backward compatibility: default US region', () => {
+    let spy = jest.spyOn(RedoclyClient.prototype, 'readCredentialsFile').mockImplementation(() => ({ token: testToken }));
+    jest.spyOn(RedoclyClient.prototype, 'setAccessTokens').mockImplementation();
+    const client = new RedoclyClient();
+    expect(client.setAccessTokens).toBeCalledWith(
+      expect.objectContaining({ us: testToken })
+    );
+    spy.mockRestore();
+  });
+
+  it('should set correct accessTokens - backward compatibility: EU region', () => {
+    let spy = jest.spyOn(RedoclyClient.prototype, 'readCredentialsFile').mockImplementation(() => ({ token: testToken }));
+    jest.spyOn(RedoclyClient.prototype, 'setAccessTokens').mockImplementation();
+    const client = new RedoclyClient('eu');
+    expect(client.setAccessTokens).toBeCalledWith(
+      expect.objectContaining({ eu: testToken })
+    );
+    spy.mockRestore();
+  });
+
+  it('should set correct accessTokens - REDOCLY_AUTHORIZATION env', () => {
+    process.env.REDOCLY_AUTHORIZATION = REDOCLY_AUTHORIZATION_TOKEN;
+    let spy = jest.spyOn(RedoclyClient.prototype, 'readCredentialsFile').mockImplementation();
+    jest.spyOn(RedoclyClient.prototype, 'setAccessTokens').mockImplementation();
+    const client = new RedoclyClient();
+    expect(client.setAccessTokens).toHaveBeenNthCalledWith(1, { "us": REDOCLY_AUTHORIZATION_TOKEN });
+    spy.mockRestore();
+  });
+
+  it('should set correct accessTokens prioritizing REDOCLY_AUTHORIZATION env over token in file', () => {
+    process.env.REDOCLY_AUTHORIZATION = REDOCLY_AUTHORIZATION_TOKEN;
+    let spy = jest.spyOn(RedoclyClient.prototype, 'readCredentialsFile').mockImplementation(() => ({ token: testToken }));
+    jest.spyOn(RedoclyClient.prototype, 'setAccessTokens').mockImplementation();
+    const client = new RedoclyClient();
+    expect(client.setAccessTokens).toHaveBeenNthCalledWith(2, { "us": REDOCLY_AUTHORIZATION_TOKEN });
+    spy.mockRestore();
+  });
+
+  it('should set correct accessTokens prioritizing REDOCLY_AUTHORIZATION env over EU token', () => {
+    process.env.REDOCLY_AUTHORIZATION = REDOCLY_AUTHORIZATION_TOKEN;
+    let spy = jest.spyOn(RedoclyClient.prototype, 'readCredentialsFile').mockImplementation(() => ({ us: testToken }));
+    jest.spyOn(RedoclyClient.prototype, 'setAccessTokens').mockImplementation();
+    const client = new RedoclyClient('eu');
+    expect(client.setAccessTokens).toHaveBeenNthCalledWith(2, { "eu": REDOCLY_AUTHORIZATION_TOKEN });
+    spy.mockRestore();
+  });
+});

package/src/redocly/index.ts

@@ -0,0 +1,182 @@
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'fs';
+import { resolve } from 'path';
+import { homedir } from 'os';
+import { green } from 'colorette';
+import { RegistryApi } from './registry-api';
+import { DEFAULT_REGION, DOMAINS, AVAILABLE_REGIONS, env } from '../config/config';
+import { RegionalToken, RegionalTokenWithValidity } from './redocly-client-types';
+import { isNotEmptyObject } from '../utils';
+
+import type { AccessTokens, Region } from '../config/types';
+
+const TOKEN_FILENAME = '.redocly-config.json';
+
+export class RedoclyClient {
+  private accessTokens: AccessTokens = {};
+  private region: Region;
+  domain: string;
+  registryApi: RegistryApi;
+
+  constructor(region?: Region) {
+    this.region = this.loadRegion(region);
+    this.loadTokens();
+    this.domain = region ? DOMAINS[region] : env.REDOCLY_DOMAIN || DOMAINS[DEFAULT_REGION];
+
+    env.REDOCLY_DOMAIN = this.domain; // isRedoclyRegistryURL depends on the value to be set
+    this.registryApi = new RegistryApi(this.accessTokens, this.region);
+  }
+
+  loadRegion(region?: Region) {
+    if (region && !DOMAINS[region]) {
+      throw new Error(`Invalid argument: region in config file.\nGiven: ${green(region)}, choices: "us", "eu".`);
+    }
+
+    if (env.REDOCLY_DOMAIN) {
+      return (AVAILABLE_REGIONS.find(
+        (region) => DOMAINS[region as Region] === env.REDOCLY_DOMAIN,
+      ) || DEFAULT_REGION) as Region;
+    }
+    return region || DEFAULT_REGION;
+  }
+
+  getRegion(): Region {
+    return this.region;
+  }
+
+  hasTokens(): boolean {
+    return isNotEmptyObject(this.accessTokens);
+  }
+
+  // <backward compatibility: old versions of portal>
+  hasToken() {
+    return !!this.accessTokens[this.region];
+  }
+
+  async getAuthorizationHeader(): Promise<string | undefined> {
+    return this.accessTokens[this.region];
+  }
+  // </backward compatibility: portal>
+
+  setAccessTokens(accessTokens: AccessTokens) {
+    this.accessTokens = accessTokens;
+  }
+
+  loadTokens(): void {
+    const credentialsPath = resolve(homedir(), TOKEN_FILENAME);
+    const credentials = this.readCredentialsFile(credentialsPath);
+    if (isNotEmptyObject(credentials)) {
+      this.setAccessTokens({
+        ...credentials,
+        ...(credentials.token &&
+          !credentials[this.region] && {
+            [this.region]: credentials.token,
+          }),
+      });
+    }
+    if (env.REDOCLY_AUTHORIZATION) {
+      this.setAccessTokens({
+        ...this.accessTokens,
+        [this.region]: env.REDOCLY_AUTHORIZATION,
+      });
+    }
+  }
+
+  getAllTokens(): RegionalToken[] {
+    return (<[Region, string][]>Object.entries(this.accessTokens))
+      .filter(([region]) => AVAILABLE_REGIONS.includes(region))
+      .map(([region, token]) => ({ region, token }));
+  }
+
+  async getValidTokens(): Promise<RegionalTokenWithValidity[]> {
+    const allTokens = this.getAllTokens();
+
+    const verifiedTokens = await Promise.allSettled(
+      allTokens.map(({ token, region }) => this.verifyToken(token, region)),
+    );
+
+    return allTokens
+      .filter((_, index) => verifiedTokens[index].status === 'fulfilled')
+      .map(({ token, region }) => ({ token, region, valid: true }));
+  }
+
+  async getTokens() {
+    return this.hasTokens() ? await this.getValidTokens() : [];
+  }
+
+  async isAuthorizedWithRedoclyByRegion(): Promise<boolean> {
+    if (!this.hasTokens()) {
+      return false;
+    }
+
+    const accessToken = this.accessTokens[this.region];
+
+    if (!accessToken) {
+      return false;
+    }
+
+    try {
+      await this.verifyToken(accessToken, this.region);
+
+      return true;
+    } catch (err) {
+      return false;
+    }
+  }
+
+  async isAuthorizedWithRedocly(): Promise<boolean> {
+    return this.hasTokens() && isNotEmptyObject(await this.getValidTokens());
+  }
+
+  readCredentialsFile(credentialsPath: string) {
+    return existsSync(credentialsPath) ? JSON.parse(readFileSync(credentialsPath, 'utf-8')) : {};
+  }
+
+  async verifyToken(
+    accessToken: string,
+    region: Region,
+    verbose: boolean = false,
+  ): Promise<{ viewerId: string; organizations: string[] }> {
+    return this.registryApi.authStatus(accessToken, region, verbose);
+  }
+
+  async login(accessToken: string, verbose: boolean = false) {
+    const credentialsPath = resolve(homedir(), TOKEN_FILENAME);
+
+    try {
+      await this.verifyToken(accessToken, this.region, verbose);
+    } catch (err) {
+      throw new Error('Authorization failed. Please check if you entered a valid API key.');
+    }
+
+    const credentials = {
+      ...this.readCredentialsFile(credentialsPath),
+      [this.region!]: accessToken,
+      token: accessToken, // FIXME: backward compatibility, remove on 1.0.0
+    };
+    this.accessTokens = credentials;
+    this.registryApi.setAccessTokens(credentials);
+    writeFileSync(credentialsPath, JSON.stringify(credentials, null, 2));
+  }
+
+  logout(): void {
+    const credentialsPath = resolve(homedir(), TOKEN_FILENAME);
+    if (existsSync(credentialsPath)) {
+      unlinkSync(credentialsPath);
+    }
+  }
+}
+
+export function isRedoclyRegistryURL(link: string): boolean {
+  const domain = env.REDOCLY_DOMAIN || DOMAINS[DEFAULT_REGION];
+
+  const legacyDomain = domain === 'redocly.com' ? 'redoc.ly' : domain;
+
+  if (
+    !link.startsWith(`https://api.${domain}/registry/`) &&
+    !link.startsWith(`https://api.${legacyDomain}/registry/`)
+  ) {
+    return false;
+  }
+
+  return true;
+}

package/src/redocly/redocly-client-types.ts

@@ -0,0 +1,10 @@
+import type { Region } from '../config/types';
+
+export interface RegionalToken {
+  region: Region;
+  token: string;
+}
+
+export interface RegionalTokenWithValidity extends RegionalToken {
+  valid: boolean;
+}

package/src/redocly/registry-api-types.ts

@@ -0,0 +1,32 @@
+export namespace RegistryApiTypes {
+  interface VersionParams {
+    organizationId: string;
+    name: string;
+    version: string;
+  }
+
+  export interface PrepareFileuploadParams extends VersionParams {
+    filesHash: string;
+    filename: string;
+    isUpsert?: boolean;
+  }
+
+  export interface PushApiParams extends VersionParams {
+    rootFilePath: string;
+    filePaths: string[];
+    branch?: string;
+    isUpsert?: boolean;
+    isPublic?: boolean;
+  }
+
+  export interface PrepareFileuploadOKResponse {
+    filePath: string;
+    signedUploadUrl: string;
+  }
+
+  export interface NotFoundProblemResponse {
+    status: 404;
+    title: 'Not Found';
+    code: 'ORGANIZATION_NOT_FOUND' | 'API_VERSION_NOT_FOUND';
+  }
+}

package/src/redocly/registry-api.ts

@@ -0,0 +1,134 @@
+import fetch, { RequestInit, HeadersInit } from 'node-fetch';
+import { RegistryApiTypes } from './registry-api-types';
+import { DEFAULT_REGION, DOMAINS } from '../config/config';
+import { isNotEmptyObject } from '../utils';
+const version = require('../../package.json').version;
+
+import type { AccessTokens, Region } from '../config/types';
+
+export class RegistryApi {
+  constructor(private accessTokens: AccessTokens, private region: Region) {}
+
+  get accessToken() {
+    return isNotEmptyObject(this.accessTokens) && this.accessTokens[this.region];
+  }
+
+  getBaseUrl(region: Region = DEFAULT_REGION) {
+    return `https://api.${DOMAINS[region]}/registry`;
+  }
+
+  setAccessTokens(accessTokens: AccessTokens) {
+    this.accessTokens = accessTokens;
+    return this;
+  }
+
+  private async request(path = '', options: RequestInit = {}, region?: Region) {
+    const headers = Object.assign({}, options.headers || {}, { 'x-redocly-cli-version': version });
+
+    if (!headers.hasOwnProperty('authorization')) {
+      throw new Error('Unauthorized');
+    }
+
+    const response = await fetch(
+      `${this.getBaseUrl(region)}${path}`,
+      Object.assign({}, options, { headers }),
+    );
+
+    if (response.status === 401) {
+      throw new Error('Unauthorized');
+    }
+
+    if (response.status === 404) {
+      const body: RegistryApiTypes.NotFoundProblemResponse = await response.json();
+      throw new Error(body.code);
+    }
+
+    return response;
+  }
+
+  async authStatus(
+    accessToken: string,
+    region: Region,
+    verbose = false,
+  ): Promise<{ viewerId: string; organizations: string[] }> {
+    try {
+      const response = await this.request('', { headers: { authorization: accessToken } }, region);
+
+      return await response.json();
+    } catch (error) {
+      if (verbose) {
+        console.log(error);
+      }
+
+      throw error;
+    }
+  }
+
+  async prepareFileUpload({
+    organizationId,
+    name,
+    version,
+    filesHash,
+    filename,
+    isUpsert,
+  }: RegistryApiTypes.PrepareFileuploadParams): Promise<RegistryApiTypes.PrepareFileuploadOKResponse> {
+    const response = await this.request(
+      `/${organizationId}/${name}/${version}/prepare-file-upload`,
+      {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          authorization: this.accessToken,
+        } as HeadersInit,
+        body: JSON.stringify({
+          filesHash,
+          filename,
+          isUpsert,
+        }),
+      },
+      this.region,
+    );
+
+    if (response.ok) {
+      return response.json();
+    }
+
+    throw new Error('Could not prepare file upload');
+  }
+
+  async pushApi({
+    organizationId,
+    name,
+    version,
+    rootFilePath,
+    filePaths,
+    branch,
+    isUpsert,
+    isPublic,
+  }: RegistryApiTypes.PushApiParams) {
+    const response = await this.request(
+      `/${organizationId}/${name}/${version}`,
+      {
+        method: 'PUT',
+        headers: {
+          'content-type': 'application/json',
+          authorization: this.accessToken,
+        } as HeadersInit,
+        body: JSON.stringify({
+          rootFilePath,
+          filePaths,
+          branch,
+          isUpsert,
+          isPublic,
+        }),
+      },
+      this.region,
+    );
+
+    if (response.ok) {
+      return;
+    }
+
+    throw new Error('Could not push api');
+  }
+}