Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add skeleton for new websockets stream api docs #1074

Open
wants to merge 8 commits into
base: main
Choose a base branch
from

Conversation

illia-malachyn
Copy link

@illia-malachyn illia-malachyn commented Jan 7, 2025

Closes onflow/flow-go#6644

  • Added a single page overview docs
  • Added a multi-page detailed docs for each message type

This is in progress and is postponed till we finish with websockets epic. However, you can review it and write notes about it.

What to add to:

  • more examples with different parameters (after integration tests are finished)
  • rate limits (when all limits are discussed and implemented)

* Added a single page overiview docs
* Added a multi-page detailed docs for each
message type
Copy link

vercel bot commented Jan 7, 2025

@illia-malachyn is attempting to deploy a commit to the Flow Team on Vercel.

A member of the Team first needs to authorize it.

@illia-malachyn
Copy link
Author

illia-malachyn commented Jan 7, 2025

Copy link

vercel bot commented Jan 10, 2025

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name Status Preview Comments Updated (UTC)
docs ❌ Failed (Inspect) Feb 27, 2025 3:13pm

@franklywatson franklywatson marked this pull request as ready for review January 11, 2025 02:04
@franklywatson
Copy link
Contributor

@illia-malachyn the deployed vercel from a few days ago is here.

With the left nav we probably want a top label that is more readable than "websockets-stream-api". This nav option is also distinct from the written title of 'Websockets Stream API'. My guess is the intention was for the sub pages to be under that root, not the 'websockets-stream-api' one

Screenshot 2025-01-13 at 11 26 32 AM Screenshot 2025-01-13 at 11 23 54 AM

@franklywatson
Copy link
Contributor

franklywatson commented Jan 15, 2025

Nav looks good in latest vercel deployment. Looks like there's still more to be added and we should wait to merge this only once the functionality is deployed and live.

Use any WebSocket client library to connect to the endpoint. Below is an example using JavaScript:

```javascript
const ws = new WebSocket('wss://api.flow.com/ws');
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let's use the correct url or an obviously fake one.

Copy link
Author

@illia-malachyn illia-malachyn Jan 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what is it ? wss://rest-mainnet.onflow.org/ws ?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's
wss://rest-mainnet.onflow.org/v1/ws

Comment on lines 22 to 24
- Each connection supports up to 10 concurrent subscriptions. Exceeding this limit will result in an error.
- Each subscription may provide up to 5 responses per second.
- After 1 minute of inactivity (no data is sent to/read from connection) connection is closed.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we should make all of these configurable, and just list the values used on the public access nodes here.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should I use up-to-date values here, or provide a link to the code where the defaults are set, or maybe scrap the values from the flow-go repo ?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

put the current defaults here. we can update them later if they are changed

@franklywatson franklywatson linked an issue Jan 29, 2025 that may be closed by this pull request
@franklywatson
Copy link
Contributor

@illia-malachyn you will need to merge from main since the project structure for the docs in this area changed.

Also, we need to make sure this section is also updated: https://developers.flow.com/networks/access-onchain-data#subscriptions

@Guitarheroua
Copy link
Contributor

@illia-malachyn you will need to merge from main since the project structure for the docs in this area changed.

Also, we need to make sure this section is also updated: https://developers.flow.com/networks/access-onchain-data#subscriptions

Created separate issue #1150 to fix the last part you mentioned, as I see we do not have any description of new gRPC subscriptions and do not mark the old implementation as deprecated.


If neither `start_block_id` nor `start_block_height` is set, the subscription will start from the latest block based on its status.

### Example Responce
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Responce => Response. here and in other places

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah we should correct those spelling errors thanks

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Contributor

@peterargue peterargue left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

added a few more comments. otherwise this is good

"subscription_id": "some-id-4",
"topic": "events",
"payload": {
"block_id": "0385...",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

does blockID include a 0x prefix?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no, it does not

@Guitarheroua
Copy link
Contributor

added a few more comments. otherwise this is good

@peterargue fixed all remarks.

@franklywatson
Copy link
Contributor

@illia-malachyn fyi vercel threw an error on deployment:

[07:10:01.508] Cloning github.com/onflow/docs (Branch: illia-malachyn/6644-new-websockets-stream-api-docs, Commit: b8cd59d)
[07:10:04.736] Cloning completed: 3.227s
[07:10:13.495] Running build in Washington, D.C., USA (East) – iad1
[07:10:14.458] Running "vercel build"
[07:10:14.983] Vercel CLI 41.2.2
[07:10:17.930] Warning: Detected "engines": { "node": ">=20" } in your `package.json` that will automatically upgrade when a new major Node.js Version is released. Learn More: http://vercel.link/node-version
[07:10:17.935] Installing dependencies...
[07:10:18.917] yarn install v1.22.19
[07:10:19.034] [1/5] Validating package.json...
[07:10:19.037] [2/5] Resolving packages...
[07:10:19.599] [3/5] Fetching packages...
[07:10:52.338] [4/5] Linking dependencies...
[07:10:52.346] warning "@cookbookdev/docsbot > @lingui/[email protected]" has unmet peer dependency "babel-plugin-macros@2 || 3".
[07:10:52.346] warning "@cookbookdev/docsbot > @monaco-editor/[email protected]" has unmet peer dependency "monaco-editor@>= 0.25.0 < 1".
[07:10:52.363] warning "@cookbookdev/docsbot > [email protected]" has incorrect peer dependency "react@^17.0.0".
[07:10:52.363] warning "@cookbookdev/docsbot > [email protected]" has incorrect peer dependency "react-dom@^17.0.0".
[07:10:52.363] warning "@cookbookdev/docsbot > @monaco-editor/react > @monaco-editor/[email protected]" has unmet peer dependency "monaco-editor@>= 0.21.0 < 1".
[07:10:52.368] warning "@docusaurus/core > [email protected]" has unmet peer dependency "react-loadable@*".
[07:10:52.379] warning "@docusaurus/core > @docusaurus/mdx-loader > @mdx-js/mdx > recma-jsx > [email protected]" has unmet peer dependency "acorn@^6.0.0 || ^7.0.0 || ^8.0.0".
[07:10:52.382] warning " > @mdx-js/[email protected]" has unmet peer dependency "@types/react@>=16".
[07:10:52.382] warning "docusaurus-theme-search-typesense > [email protected]" has unmet peer dependency "algoliasearch@>= 3.1 < 6".
[07:10:52.383] warning "@docusaurus/preset-classic > @docusaurus/theme-search-algolia > @docsearch/react > @algolia/[email protected]" has unmet peer dependency "@algolia/client-search@>= 4.9.1 < 6".
[07:10:52.383] warning "@docusaurus/preset-classic > @docusaurus/theme-search-algolia > @docsearch/react > @algolia/autocomplete-core > @algolia/[email protected]" has unmet peer dependency "search-insights@>= 1 < 3".
[07:10:52.383] warning "@docusaurus/preset-classic > @docusaurus/theme-search-algolia > @docsearch/react > @algolia/autocomplete-core > @algolia/[email protected]" has unmet peer dependency "@algolia/client-search@>= 4.9.1 < 6".
[07:10:52.383] warning "@onflow/fcl > @onflow/fcl-core > @improbable-eng/[email protected]" has unmet peer dependency "google-protobuf@^3.14.0".
[07:10:52.384] warning " > [email protected]" has unmet peer dependency "@docusaurus/theme-common@^3.5.2".
[07:10:52.384] warning "docusaurus-theme-search-typesense > [email protected]" has unmet peer dependency "@babel/runtime@^7.17.2".
[07:10:52.384] warning "docusaurus-theme-search-typesense > typesense-docsearch-react > @algolia/[email protected]" has unmet peer dependency "@algolia/client-search@>= 4.9.1 < 6".
[07:10:52.384] warning "docusaurus-theme-search-typesense > typesense-docsearch-react > @algolia/[email protected]" has unmet peer dependency "algoliasearch@>= 4.9.1 < 6".
[07:10:52.384] warning "docusaurus-theme-search-typesense > typesense-docsearch-react > [email protected]" has unmet peer dependency "@babel/runtime@^7.23.2".
[07:10:52.384] warning " > [email protected]" has unmet peer dependency "@docusaurus/theme-common@^3.0.0".
[07:10:52.385] warning " > [email protected]" has unmet peer dependency "@docusaurus/utils@^3.0.0".
[07:10:52.385] warning "redocusaurus > [email protected]" has unmet peer dependency "@docusaurus/utils@^3.0.0".
[07:10:52.385] warning "redocusaurus > [email protected]" has unmet peer dependency "@docusaurus/theme-common@^3.0.0".
[07:10:52.385] warning "redocusaurus > [email protected]" has unmet peer dependency "webpack@^5.0.0".
[07:10:52.385] warning "redocusaurus > docusaurus-plugin-redoc > [email protected]" has unmet peer dependency "core-js@^3.1.4".
[07:10:52.385] warning "redocusaurus > docusaurus-plugin-redoc > [email protected]" has unmet peer dependency "mobx@^6.0.4".
[07:10:52.385] warning "redocusaurus > docusaurus-plugin-redoc > [email protected]" has unmet peer dependency "styled-components@^4.1.1 || ^5.1.1 || ^6.0.5".
[07:10:52.385] warning "redocusaurus > docusaurus-plugin-redoc > redoc > @cfaester/[email protected]" has unmet peer dependency "enzyme@^3.11.0".
[07:10:52.385] warning "redocusaurus > docusaurus-plugin-redoc > redoc > [email protected]" has unmet peer dependency "mobx@^6.9.0".
[07:10:52.386] warning "redocusaurus > docusaurus-plugin-redoc > redoc > mobx-react > [email protected]" has unmet peer dependency "mobx@^6.9.0".
[07:10:52.386] warning " > @typescript-eslint/[email protected]" has unmet peer dependency "@typescript-eslint/parser@^8.0.0 || ^8.0.0-alpha.0".
[07:10:52.387] warning " > [email protected]" has incorrect peer dependency "@typescript-eslint/eslint-plugin@^6.4.0".
[07:10:52.389] warning " > [email protected]" has unmet peer dependency "@types/node@*".
[07:11:16.234] [5/5] Building fresh packages...
[07:11:26.532] Done in 67.62s.
[07:11:26.757] yarn run v1.22.19
[07:11:26.782] $ ./scripts/import.sh && docusaurus build
[07:11:26.795] Importing...
[07:11:26.795] Cloning repos...
[07:11:26.805] Entry 1:
[07:11:26.806] Repository Owner: onflow
[07:11:26.806] Repository Name: flow-ft
[07:11:26.806] Repository Branch: master
[07:11:26.806] 
[07:11:26.807] Cloning into './temp/flow-ft'...
[07:11:27.532] Data 1
[07:11:27.532] Source: docs/
[07:11:27.532] Dest: build/core-contracts/flow-ft/
[07:11:27.532] Do copy: false
[07:11:27.532] 
[07:11:27.532] Skipping copy
[07:11:27.538] Entry 2:
[07:11:27.539] Repository Owner: onflow
[07:11:27.539] Repository Name: flow-nft
[07:11:27.539] Repository Branch: master
[07:11:27.539] 
[07:11:27.540] Cloning into './temp/flow-nft'...
[07:11:28.191] Data 1
[07:11:28.191] Source: docs/
[07:11:28.191] Dest: build/core-contracts/flow-nft/
[07:11:28.191] Do copy: false
[07:11:28.191] 
[07:11:28.191] Skipping copy
[07:11:28.197] Entry 3:
[07:11:28.197] Repository Owner: ph0ph0
[07:11:28.197] Repository Name: Get-The-Flow-Down
[07:11:28.197] Repository Branch: master
[07:11:28.197] 
[07:11:28.198] Cloning into './temp/Get-The-Flow-Down'...
[07:11:28.322] Data 1
[07:11:28.322] Source: 
[07:11:28.322] Dest: ecosystem/overview/
[07:11:28.322] Do copy: true
[07:11:28.322] 
[07:11:28.322] Copying files from ./temp/Get-The-Flow-Down/ to ./docs/ecosystem/overview/
[07:11:31.122] [INFO] [en] Creating an optimized production build...
[07:11:32.628] [WARNING] Cannot infer the update date for some files, as they are not tracked by git.
[07:11:33.339] [info] [webpackbar] Compiling Client
[07:11:33.359] [info] [webpackbar] Compiling Server
[07:12:32.452] [success] [webpackbar] Server: Compiled successfully in 59.09s
[07:13:11.248] [success] [webpackbar] Client: Compiled successfully in 1.63m
[07:13:11.272] [WARNING] {"moduleIdentifier":"/vercel/path0/node_modules/@walletconnect/jsonrpc-ws-connection/node_modules/ws/lib/buffer-util.js","moduleName":"./node_modules/@walletconnect/jsonrpc-ws-connection/node_modules/ws/lib/buffer-util.js","loc":"105:21-42","message":"Module not found: Error: Can't resolve 'bufferutil' in '/vercel/path0/node_modules/@walletconnect/jsonrpc-ws-connection/node_modules/ws/lib'","compilerPath":"server"}
[07:13:11.273] [WARNING] {"moduleIdentifier":"/vercel/path0/node_modules/@walletconnect/jsonrpc-ws-connection/node_modules/ws/lib/validation.js","moduleName":"./node_modules/@walletconnect/jsonrpc-ws-connection/node_modules/ws/lib/validation.js","loc":"86:20-45","message":"Module not found: Error: Can't resolve 'utf-8-validate' in '/vercel/path0/node_modules/@walletconnect/jsonrpc-ws-connection/node_modules/ws/lib'","compilerPath":"server"}
[07:13:11.273] [WARNING] {"moduleIdentifier":"/vercel/path0/node_modules/ws/lib/buffer-util.js","moduleName":"./node_modules/ws/lib/buffer-util.js","loc":"117:23-44","message":"Module not found: Error: Can't resolve 'bufferutil' in '/vercel/path0/node_modules/ws/lib'","compilerPath":"server"}
[07:13:11.273] [WARNING] {"moduleIdentifier":"/vercel/path0/node_modules/ws/lib/validation.js","moduleName":"./node_modules/ws/lib/validation.js","loc":"144:24-49","message":"Module not found: Error: Can't resolve 'utf-8-validate' in '/vercel/path0/node_modules/ws/lib'","compilerPath":"server"}
[07:13:11.273] [WARNING] {"moduleIdentifier":"javascript/dynamic|/vercel/path0/node_modules/pino/lib/tools.js","moduleName":"./node_modules/pino/lib/tools.js","loc":"219:26-62","message":"Module not found: Error: Can't resolve 'pino-pretty' in '/vercel/path0/node_modules/pino/lib'","compilerPath":"server"}
[07:13:17.672] Dapp running on network: testnet
[07:13:25.661] 
[07:13:25.664] [ERROR] Error: Unable to build website for locale en.
[07:13:25.664]     at tryToBuildLocale (/vercel/path0/node_modules/@docusaurus/core/lib/commands/build/build.js:78:15)
[07:13:25.664]     at async /vercel/path0/node_modules/@docusaurus/core/lib/commands/build/build.js:34:9
[07:13:25.664]     ... 4 lines matching cause stack trace ...
[07:13:25.664]     at async file:///vercel/path0/node_modules/@docusaurus/core/bin/docusaurus.mjs:44:3 {
[07:13:25.664]   [cause]: Error: Docusaurus static site generation failed for 1 paths:
[07:13:25.664]   - "/"
[07:13:25.664]       at generateStaticFiles (/vercel/path0/node_modules/@docusaurus/core/lib/ssg/ssg.js:129:15)
[07:13:25.664]       at async executeSSG (/vercel/path0/node_modules/@docusaurus/core/lib/ssg/ssgExecutor.js:29:23)
[07:13:25.664]       ... 9 lines matching cause stack trace ...
[07:13:25.664]       at async file:///vercel/path0/node_modules/@docusaurus/core/bin/docusaurus.mjs:44:3 {
[07:13:25.665]     [cause]: AggregateError
[07:13:25.665]         at generateStaticFiles (/vercel/path0/node_modules/@docusaurus/core/lib/ssg/ssg.js:130:20)
[07:13:25.665]         at async executeSSG (/vercel/path0/node_modules/@docusaurus/core/lib/ssg/ssgExecutor.js:29:23)
[07:13:25.665]         at async buildLocale (/vercel/path0/node_modules/@docusaurus/core/lib/commands/build/buildLocale.js:60:31)
[07:13:25.665]         at async runBuildLocaleTask (/vercel/path0/node_modules/@docusaurus/core/lib/commands/build/build.js:93:5)
[07:13:25.665]         at async /vercel/path0/node_modules/@docusaurus/core/lib/commands/build/build.js:74:13
[07:13:25.665]         at async tryToBuildLocale (/vercel/path0/node_modules/@docusaurus/core/lib/commands/build/build.js:70:9)
[07:13:25.665]         at async /vercel/path0/node_modules/@docusaurus/core/lib/commands/build/build.js:34:9
[07:13:25.665]         at async mapAsyncSequential (/vercel/path0/node_modules/@docusaurus/utils/lib/jsUtils.js:21:24)
[07:13:25.665]         at async Command.build (/vercel/path0/node_modules/@docusaurus/core/lib/commands/build/build.js:33:5)
[07:13:25.665]         at async Promise.all (index 0)
[07:13:25.665]         at async runCLI (/vercel/path0/node_modules/@docusaurus/core/lib/commands/cli.js:56:5)
[07:13:25.665]         at async file:///vercel/path0/node_modules/@docusaurus/core/bin/docusaurus.mjs:44:3 {
[07:13:25.665]       [errors]: [
[07:13:25.665]         Error: Can't render static file for pathname "/"
[07:13:25.665]             at generateStaticFile (/vercel/path0/node_modules/@docusaurus/core/lib/ssg/ssg.js:167:15)
[07:13:25.665]             at processTicksAndRejections (node:internal/process/task_queues:105:5)
[07:13:25.665]             at runNextTicks (node:internal/process/task_queues:69:3)
[07:13:25.665]             at process.processImmediate (node:internal/timers:459:9)
[07:13:25.665]             at async /vercel/path0/node_modules/p-map/index.js:57:22 {
[07:13:25.665]           [cause]: Error: Unexpected: no Docusaurus route context found
[07:13:25.666]               at mergeContexts (server.bundle.js:515251:154)
[07:13:25.666]               at server.bundle.js:515253:214
[07:13:25.666]               at Object.Ic [as useMemo] (server.bundle.js:610029:240)
[07:13:25.666]               at exports.useMemo (server.bundle.js:612509:48)
[07:13:25.666]               at RouteContextProvider (server.bundle.js:515253:209)
[07:13:25.666]               at Uc (server.bundle.js:610036:44)
[07:13:25.666]               at Xc (server.bundle.js:610038:253)
[07:13:25.666]               at Z (server.bundle.js:610044:89)
[07:13:25.666]               at Vc (server.bundle.js:610036:473)
[07:13:25.666]               at Xc (server.bundle.js:610038:210)
[07:13:25.666]         }
[07:13:25.666]       ]
[07:13:25.667]     }
[07:13:25.667]   }
[07:13:25.667] }
[07:13:25.667] [INFO] Docusaurus version: 3.6.3
[07:13:25.667] Node version: v22.14.0
[07:13:25.805] error Command failed with exit code 1.
[07:13:25.805] info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
[07:13:25.824] Error: Command "sed -i '/process.env.DEBUG = namespaces;/c\// process.env.DEBUG = namespaces;' ./node_modules/debug/src/node.js && yarn build" exited with 1
[07:13:27.066] 

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[Access] Add documentation for new websockets [Access] Add examples for ws conn usages
6 participants