Optic CI support for resolving HTTP URLs in $refs

[cmars]

In https://github.com/snyk/vervet/pull/143/files we're introducing rudimentary schema versioning by referencing common OpenAPI components (out of this project in fact, see components at the top level). Because this project's releases use semantically versioned tags, we can reference a stable version of these models using these tags, directly out of Github.

For faster moving, iteratively developed models, this may not very sustainable (background discussion ongoing around this, with lockfiles, etc), but it may be just fine for structural common components that are not likely change very often.

In testing our support for HTTP $refs, we found that optic-ci does not resolve HTTP references though:

Comparing (commit 67f261ceaad5068b3a0683559981c15f7089ac62):src/web/routes/api/v3/resources/targets/2021-08-20/spec.yaml to /Users/cmars/Projects/registry/src/web/routes/api/v3/resources/targets/2021-08-20/spec.yaml
Error loading file: {"errno":-2,"code":"ENOENT","syscall":"open","path":"https://raw.githubusercontent.com/snyk/sweater-comb/v1.2.0/components/responses/400.yaml"}

We'd like to have support for resolving and fetching the contents of HTTP URLs in $ref.

[cmars]

CC @acunniffe

[acunniffe]

Hey @cmars -- this sounds like a great starting approach for shared schemas.

We should have full support for resolving URLs. Under the hood Optic uses https://github.com/APIDevTools/json-schema-ref-parser which is one of the most robust ref parser used by many tools in the API space.

We'll dig in today and figure out why those aren't working in your case, there are other teams using URLs today 🤔. I wonder if it has something to do with the headers GitHub sets.

Will revert later today.

[cmars]

It looks like the functionality is there: https://github.com/APIDevTools/json-schema-ref-parser/blob/b6f968bc7380656258c02aacba2d766b0118e573/lib/resolvers/http.js

Maybe the resolver needs to be registered somewhere?

[cmars]

I'll update the e2e script tests with http $refs, perhaps that will help shed more light, isolate the problem, etc

[acunniffe]

We have a theory @cmars -- I suspect it will work in the e2e script.

There is a custom resolver that allows Optic to load git rev:name syntax. Basically it needs to make sure that when you $ref to another file in the repo, it gets the correct version of that file (the one in the same commit sha).

Since e2e uses the normal implementation I would wager it loads fine.

There's a fix in the works and we're testing it on our side too

[cmars]

Set this up in #173, seeing the same errors for compare and bulk-compare:

zksnyk:sweater-comb cmars$ ./end-end-tests/api-standards/test.bash
{"changeDate":"2021-11-11","changeResource":"thing","changeVersion":{"date":"2021-11-10","stability":"experimental"},"resourceVersionReleases":{}}
yarn run v1.22.11
$ yarn ts-node src/index.ts compare --to /Users/cmars/Projects/sweater-comb/end-end-tests/api-standards/resources/thing/2021-11-10/000-baseline.yaml --context '{"changeDate":"2021-11-11","changeResource":"thing","changeVersion":{"date":"2021-11-10","stability":"experimental"},"resourceVersionReleases":{}}'
$ /Users/cmars/Projects/sweater-comb/node_modules/.bin/ts-node src/index.ts compare --to /Users/cmars/Projects/sweater-comb/end-end-tests/api-standards/resources/thing/2021-11-10/000-baseline.yaml --context '{"changeDate":"2021-11-11","changeResource":"thing","changeVersion":{"date":"2021-11-10","stability":"experimental"},"resourceVersionReleases":{}}'
Loading specifications for comparison:
Current specification: done
Next specification: done
running rules...
Error running rules: "ENOENT: no such file or directory, open 'https://raw.githubusercontent.com/snyk/sweater-comb/v1.2.0/components/parameters/version.yaml'"
ENOENT: no such file or directory, open 'https://raw.githubusercontent.com/snyk/sweater-comb/v1.2.0/components/parameters/version.yaml'
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
zksnyk:sweater-comb cmars$ ./end-end-tests/api-standards/test-bulk.bash
*** TEST: 'from scratch' comparisons of well-formed OpenAPI ***
yarn run v1.22.11
$ yarn ts-node src/index.ts bulk-compare --input /var/folders/xg/5fst00tj1m7gxf88yxqvrhfr0000gp/T/tmp.KS3RVFY8/from_scratch
$ /Users/cmars/Projects/sweater-comb/node_modules/.bin/ts-node src/index.ts bulk-compare --input /var/folders/xg/5fst00tj1m7gxf88yxqvrhfr0000gp/T/tmp.KS3RVFY8/from_scratch
Reading input file...
Bulk comparing

Comparing Empty spec to /Users/cmars/Projects/sweater-comb/end-end-tests/api-standards/resources/thing/2021-11-10/000-baseline.yaml
Error loading file: {"errno":-2,"code":"ENOENT","syscall":"open","path":"https://raw.githubusercontent.com/snyk/sweater-comb/v1.2.0/components/parameters/version.yaml"}

error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.