chore: OpenAPI spec changes & other support for running localenv in docker windows #2530

mkurapov · 2024-03-12T13:25:00Z

Changes proposed in this pull request

Update how we handle OpenAPI specs in the repo
Remove the BEFORE_MERGED variable from our localenv:compose commands
Add doc section to local playground overview with known issues

Context

This PR makes localenv work inside docker for windows (whether that's through hyper-v or WSL).

Symlinked Schemas

The main issue that prevented this working previously were the symlinked OpenAPI schemas (in packages/*/src/openapi) that docker for windows couldn't copy over as a proper file when creating the docker images.
This led me down the road to a bigger refactor of how we were handling OpenAPI specs in the repo in general.

Usually, we used the fetch-schemas script to pull the latest OpenAPI schemas into the root openapi folder, where we would from there, symlink to them from packages/(backend | auth | token-introspection)/src/openapi. We needed to do that for:

Creating OpenAPI validators with (eg):

await createOpenAPI(
   path.resolve(__dirname, './openapi/resource-server.yaml')
)

Being able to have references to the schemas, so we could reference components in auth-server.yaml, for example, how we do in token-introspection.yaml:

rafiki/packages/token-introspection/src/openapi/token-introspection.yaml

Lines 70 to 71 in 96061ff

access:

$ref: ./auth-server.yaml#/components/schemas/access

The first "problem" was solved by being able to directly import the OpenAPI objects from the updated open-payments library:

feat(open-payments): export OpenAPI specs open-payments#440

allowing us to do validation as such:

rafiki/packages/backend/src/index.ts

Lines 157 to 165 in aa55604

    
           container.singleton('openApi', async () => { 
        
             const resourceServerSpec = await getResourceServerOpenAPI() 
        
             const walletAddressServerSpec = await getWalletAddressServerOpenAPI() 
        
             return { 
        
               resourceServerSpec, 
        
               walletAddressServerSpec 
        
             } 
        
           })

This is handy because it allows us to remove the fetch-schemas script, and it means that the spec in the open payments client we use in the repo will always be consistent with the spec that we validate against when checking the Open Payment API requests and responses.

However, this didn't fully solve the issue 2: how can we still have references to the yaml files such that we could extend them in our other OpenAPI files (namely, token-introspection.yaml and id-provided.yaml, which both reference the auth-server.yaml & shared schemas.yaml?

This was a bit tricky, and maybe there is a better solution, but this ends up working by using a postinstall command, that copies over the bundled yaml files in the node_modules/@interledger/open-payments/...folder into the respective (auth | token-introspection)/src/openapi/specs folder when doing pnpm install:

rafiki/packages/token-introspection/package.json

Lines 13 to 15 in dceeb40

    
           "copy-op-schemas": "cp ./node_modules/@interledger/open-payments/dist/openapi/specs/auth-server.yaml ./node_modules/@interledger/open-payments/dist/openapi/specs/schemas.yaml ./src/openapi/specs/", 
        
           "generate:types": "openapi-typescript ../../openapi/token-introspection.yaml --output src/openapi/generated/types.ts -t", 
        
           "postinstall":"pnpm copy-op-schemas",

Since this ends up being kind of a generated file, we should .gitignore them:

rafiki/.gitignore

Lines 60 to 64 in aa55604

    
           # Open Payments schemas 
        
           packages/**/src/openapi/specs/schemas.yaml 
        
           packages/**/src/openapi/specs/auth-server.yaml 
        
           packages/**/src/openapi/specs/resource-server.yaml 
        
           packages/**/src/openapi/specs/wallet-address-server.yaml

Question

Related to a suggestion from @BlairCurrey: should we have a sibling openapi package in the repo that basically holds all of our OpenAPI yaml files, such that we can export and use the the OpenAPI validators in backend and auth all from
one spot?
This way, we can just do this postinstall command in one place to get the Open Payments specs. The downsides of this: the files that backend and auth use separately are not in their corresponding repos and we would need to reference this package when generating the TS types for the token-introspection package.

Other issues

Other issues that prevented running localenv in windows docker were:

the pnpm localenv:compose commands do not work because of the BEFORE_MERGED variable usage
- this was fixed just by writing out the commands in-line
the tigerbeetle container was killed upon startup:
- this was actually a documented issue , and its fixed just by increasing the available RAM in the VM. I added documentation for this.

Fixes #1562

Checklist

This reverts commit c4a0199.

# Please enter a commit message to explain why this merge is necessary, # especially if it merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the commit.

# Conflicts: # package.json

…uild time

netlify · 2024-03-12T13:25:16Z

✅ Deploy Preview for brilliant-pasca-3e80ec ready!

Name	Link
🔨 Latest commit	`d7d597b`
🔍 Latest deploy log	https://app.netlify.com/sites/brilliant-pasca-3e80ec/deploys/65f9a9004361cd000869f00e
😎 Deploy Preview	https://deploy-preview-2530--brilliant-pasca-3e80ec.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

mkurapov · 2024-03-15T13:00:54Z

localenv/mock-account-servicing-entity/Dockerfile

-RUN apk add --no-cache \
-    python3 \
-    make \
-    g++


was breaking on windows, and looks like not needed in general

@raducristianpopa specified in the original pr that this is for node-gyp. #1795 (comment) Could node-gyp be included with pnpm? It's liable to be used by some of our packages and its hard to say what. I did remove from backend and start localenv OK FWIW. Looks like npm does include an internal version (so maybe pnpm does too), although im not clear on if this would be available to packages: https://github.com/nodejs/node-gyp/blob/main/docs/Updating-npm-bundled-node-gyp.md#updating-the-npm-bundled-version-of-node-gyp

There was a dependency chain within testcontainers that needed these packages (Python, C/C++ compiler) and I was following their requirements. I recall discussing with Max about this some time ago and it was working for me without installing them at that time.

mkurapov · 2024-03-15T13:01:21Z

packages/token-introspection/src/openapi/specs/token-introspection.yaml

@@ -0,0 +1,116 @@
+openapi: 3.1.0


no changes, just moved under openapi/specs folder

BlairCurrey · 2024-03-18T17:08:24Z

noticed when trying to setup on windows that pnpm -r build (in README.md docs) fails (see it on mac too). Looks like the spec dir gets created by token-introspection then fails when we try to do it again:

blaircurrey@blairs-MacBook-Pro-2 rafiki % pnpm -r build
Scope: 6 of 7 workspace projects
localenv/mock-account-servicing-entity build$ remix build
│ [info] building... (NODE_ENV=production)
│ [info] built (340ms)
└─ Done in 2.3s
packages/token-introspection build$ pnpm clean && tsc --build tsconfig.json && pnpm copy-files
│ > token-introspection@ clean /Users/blaircurrey/code/interledger/rafiki/packages/token-introspection
│ > rm -fr dist/
│ > token-introspection@ copy-files /Users/blaircurrey/code/interledger/rafiki/packages/token-introspection
│ > mkdir ./dist/openapi/specs && cp -r ./src/openapi/specs/*.yaml ./dist/openapi/specs/
└─ Done in 1.1s
packages/frontend build$ remix build
│ [info] building... (NODE_ENV=production)
│ [info] built (770ms)
└─ Done in 2.3s
packages/auth build$ pnpm build:deps && pnpm clean && tsc --build tsconfig.json && pnpm copy-files
│ > auth@ build:deps /Users/blaircurrey/code/interledger/rafiki/packages/auth
│ > pnpm --filter token-introspection build
│ > token-introspection@ build /Users/blaircurrey/code/interledger/rafiki/packages/token-introspection
│ > pnpm clean && tsc --build tsconfig.json && pnpm copy-files
│ > token-introspection@ clean /Users/blaircurrey/code/interledger/rafiki/packages/token-introspection
│ > rm -fr dist/
│ > token-introspection@ copy-files /Users/blaircurrey/code/interledger/rafiki/packages/token-introspection
│ > mkdir ./dist/openapi/specs && cp -r ./src/openapi/specs/*.yaml ./dist/openapi/specs/
│ mkdir: ./dist/openapi/specs: File exists
│  ELIFECYCLE  Command failed with exit code 1.
│ /Users/blaircurrey/code/interledger/rafiki/packages/token-introspection:
│  ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL  token-introspection@ build: `pnpm clean && tsc --build tsconfig.json && pnpm copy-files`
│ Exit status 1
│  ELIFECYCLE  Command failed with exit code 1.
└─ Failed in 1.5s at /Users/blaircurrey/code/interledger/rafiki/packages/auth
packages/backend build$ pnpm build:deps && pnpm clean && tsc --build tsconfig.json && pnpm copy-files
│ > backend@ build:deps /Users/blaircurrey/code/interledger/rafiki/packages/backend
│ > pnpm --filter token-introspection build
│ > token-introspection@ build /Users/blaircurrey/code/interledger/rafiki/packages/token-introspection
│ > pnpm clean && tsc --build tsconfig.json && pnpm copy-files
│ > token-introspection@ clean /Users/blaircurrey/code/interledger/rafiki/packages/token-introspection
│ > rm -fr dist/
│ > token-introspection@ copy-files /Users/blaircurrey/code/interledger/rafiki/packages/token-introspection
│ > mkdir ./dist/openapi/specs && cp -r ./src/openapi/specs/*.yaml ./dist/openapi/specs/
└─ Running...
/Users/blaircurrey/code/interledger/rafiki/packages/auth:
 ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL  auth@ build: `pnpm build:deps && pnpm clean && tsc --build tsconfig.json && pnpm copy-files`
Exit status 1

See mkdir: ./dist/openapi/specs: File exists in auth build

mkurapov · 2024-03-18T18:02:27Z

@BlairCurrey got it, thanks! Updated the mkdir command

# Conflicts: # openapi/auth-server.yaml # openapi/schemas.yaml # scripts/fetch-schemas.sh

sabineschaller

Is there something in the docs that talks about when to run the postinstall?

mkurapov · 2024-03-19T13:57:51Z

@sabineschaller

Is there something in the docs that talks about when to run the postinstall?

postinstall runs automatically after every pnpm i: https://docs.npmjs.com/cli/v10/using-npm/scripts#life-cycle-operation-order

sabineschaller · 2024-03-19T14:06:26Z

Of course 🤦‍♀️

mkurapov added 14 commits July 6, 2023 17:08

chore: remove all symlinks

c4a0199

Revert "chore: remove all symlinks"

77752b2

This reverts commit c4a0199.

chore: remove all symlinks

c9325d4

chore: include actual yaml spec files

c507eca

chore: update localenv commands

f652239

Merge branch 'main' into windows

3ad1675

# Please enter a commit message to explain why this merge is necessary, # especially if it merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the commit.

chore: update openapi specs

d1c798f

dockerfiles: remove apk add step

5af1685

remove engine-strict form npmrc

e0bd8fd

Merge branch 'main' into windows

e0f59cc

# Conflicts: # package.json

Merge branch 'main' into windows

1547133

chore(auth, backend): remove unneeded token-introspection openapi

b9b0fe2

chore(auth, backend): removing openapi specs from src/, copy during b…

4e23fcb

…uild time

chore: move token-introspection.yaml to root openapi folder

4ec5323

github-actions bot added pkg: backend Changes in the backend package. pkg: frontend Changes in the frontend package. type: source Changes business logic pkg: auth Changes in the GNAP auth package. pkg: mock-ase labels Mar 12, 2024

mkurapov added 10 commits March 14, 2024 19:06

feat: imports OpenAPI specs from open-payments

8bab11a

feat(token-introspection): export OpenAPI spec from package

a8ad05e

chore(token-introspection): update test

a265789

chore(auth): update id-provder.yaml location

bb34b9f

chore(auth, backend, token-introspection): update op library

0a886b0

chore(auth, token-introspection): update postinstall scripts

b159c21

chore(backend, auth): remove openapi copy from dockerfile

90e3acb

chore: gitignore copied over Open Payments schemas

00823fb

chore: remove fetch-schemas script

2e9dc5e

chore: re-introduce engine-strict=true

0a9eea8

github-actions bot added pkg: documentation Changes in the documentation package. type: documentation (archived) Improvements or additions to documentation labels Mar 15, 2024

mkurapov marked this pull request as ready for review March 15, 2024 12:41

mkurapov requested review from melissahenderson and hajjimo as code owners March 15, 2024 12:41

mkurapov requested review from BlairCurrey and sabineschaller March 15, 2024 12:41

docs: add docs describing common issues in local playground

2fb0a50

github-actions bot added the type: localenv Local playground label Mar 15, 2024

docs: update references to openapi schemas

e23fdca

mkurapov commented Mar 15, 2024

View reviewed changes

chore: update mkdir command to ignore existing dir

a391ece

mkurapov removed request for melissahenderson and hajjimo March 18, 2024 18:04

mkurapov added 6 commits March 18, 2024 19:09

chore(backend): copy op schemas on postinstall for consistency

4d59e94

Merge branch 'main' into windows

ce1b51f

# Conflicts: # openapi/auth-server.yaml # openapi/schemas.yaml # scripts/fetch-schemas.sh

Merge branch 'main' into windows

7a9c2ae

chore(ci): validate webhook OpenAPI yaml

403612d

Merge branch 'main' into windows

47fe113

chore: fix pnpm lock file

f8d58c7

sabineschaller approved these changes Mar 19, 2024

View reviewed changes

Merge branch 'main' into windows

d7d597b

mkurapov merged commit f089930 into main Mar 19, 2024
22 checks passed

mkurapov deleted the windows branch March 19, 2024 15:16

mkurapov mentioned this pull request Mar 19, 2024

feat: new rafiki release pipeline and nodejs bump to v20 #2510

Merged

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore: OpenAPI spec changes & other support for running localenv in docker windows #2530

chore: OpenAPI spec changes & other support for running localenv in docker windows #2530

mkurapov commented Mar 12, 2024 •

edited

Loading

netlify bot commented Mar 12, 2024 •

edited

Loading

mkurapov Mar 15, 2024

BlairCurrey Mar 18, 2024 •

edited

Loading

raducristianpopa Mar 19, 2024 •

edited

Loading

mkurapov Mar 15, 2024

BlairCurrey commented Mar 18, 2024 •

edited

Loading

mkurapov commented Mar 18, 2024

sabineschaller left a comment

mkurapov commented Mar 19, 2024

sabineschaller commented Mar 19, 2024

	container.singleton('openApi', async () => {
	const resourceServerSpec = await getResourceServerOpenAPI()
	const walletAddressServerSpec = await getWalletAddressServerOpenAPI()

	return {
	resourceServerSpec,
	walletAddressServerSpec
	}
	})

	"copy-op-schemas": "cp ./node_modules/@interledger/open-payments/dist/openapi/specs/auth-server.yaml ./node_modules/@interledger/open-payments/dist/openapi/specs/schemas.yaml ./src/openapi/specs/",
	"generate:types": "openapi-typescript ../../openapi/token-introspection.yaml --output src/openapi/generated/types.ts -t",
	"postinstall":"pnpm copy-op-schemas",

	# Open Payments schemas
	packages/**/src/openapi/specs/schemas.yaml
	packages/**/src/openapi/specs/auth-server.yaml
	packages/**/src/openapi/specs/resource-server.yaml
	packages/**/src/openapi/specs/wallet-address-server.yaml

	access:
	$ref: ./auth-server.yaml#/components/schemas/access

chore: OpenAPI spec changes & other support for running localenv in docker windows #2530

chore: OpenAPI spec changes & other support for running localenv in docker windows #2530

Conversation

mkurapov commented Mar 12, 2024 • edited Loading

Changes proposed in this pull request

Context

Symlinked Schemas

Question

Other issues

Checklist

netlify bot commented Mar 12, 2024 • edited Loading

✅ Deploy Preview for brilliant-pasca-3e80ec ready!

mkurapov Mar 15, 2024

Choose a reason for hiding this comment

BlairCurrey Mar 18, 2024 • edited Loading

Choose a reason for hiding this comment

raducristianpopa Mar 19, 2024 • edited Loading

Choose a reason for hiding this comment

mkurapov Mar 15, 2024

Choose a reason for hiding this comment

BlairCurrey commented Mar 18, 2024 • edited Loading

mkurapov commented Mar 18, 2024

sabineschaller left a comment

Choose a reason for hiding this comment

mkurapov commented Mar 19, 2024

sabineschaller commented Mar 19, 2024

mkurapov commented Mar 12, 2024 •

edited

Loading

netlify bot commented Mar 12, 2024 •

edited

Loading

BlairCurrey Mar 18, 2024 •

edited

Loading

raducristianpopa Mar 19, 2024 •

edited

Loading

BlairCurrey commented Mar 18, 2024 •

edited

Loading