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

reference docs for network Port API #8852

Closed
2 tasks done
Tracked by #1031
dckc opened this issue Jan 31, 2024 · 3 comments
Closed
2 tasks done
Tracked by #1031

reference docs for network Port API #8852

dckc opened this issue Jan 31, 2024 · 3 comments
Assignees
Labels
documentation Improvements or additions to documentation enhancement New feature or request needs-design

Comments

@dckc
Copy link
Member

dckc commented Jan 31, 2024

What is the Problem Being Solved?

As a developer on the Agoric platform, I want to understand the network port API.

p.s. resolution: reference docs for @agoric/network package.

Description of the Design / Test Plan

As in the @agoric/network package README:

  • Connecting to a Remote Port
  • Opening a Listening Port and Accepting an Inbound Connection
  • Sending Data
  • Receiving Data
  • Closing the Connection
  • Removing a Listener
  • Closing the Port Entirely

See also unit tests:

agoric-sdk/packages/vats$ yarn test test/network.test.js
  ✔ network - ibc (131ms)
    ℹ Opening a Listening Port
    ℹ Accepting an Inbound Connection
    ℹ Sending Data - echo
    ℹ Receiving Data hello198
    ℹ Closing the Connection
    ℹ Connecting to a Remote Port
    ℹ Sending Data - transfer
    ℹ Receiving Data inbound-msg

use the typedoc approach (#8720) and refine the source code until the generated docs are adequate.
The usual PR review process seems sufficient to judge adequacy of reference docs.

  • url / publishing mechanics
    • cloudflare pages?

punted these from the critical path:

Security / Scaling / Upgrade Considerations

n/a

background

In reviewing a recent PR aimed at adding the network-vat in an upcoming release (#8721), I learned that the network vat -- the Port API at least -- is part of the developer API product. So it needs reference docs.

cc @sufyaankhan @michaelfig @iomekam @turadg

@dckc dckc added the enhancement New feature or request label Jan 31, 2024
@dckc
Copy link
Member Author

dckc commented Feb 2, 2024

I broke ground: 035eafb

rendered: https://ag-api-docs-net.netlify.app/modules/_agoric_network.html
(manually deployed to netlify)

@dckc
Copy link
Member Author

dckc commented Feb 7, 2024

for stuff that's not part of the developer API product:

@dckc
Copy link
Member Author

dckc commented Apr 22, 2024

Generated docs for @agoric/network are available at https://agoric-sdk.pages.dev/modules/_agoric_network as part of #1032 .

And in changes such as ae0e43e , we seem to be keeping them up-to-date.
cc @0xpatrickdev @michaelfig @gibson042 @warner

I suppose this bit is outdated; doesn't do much harm, though:

<!--
  content should remain synchronized with
  https://github.com/Agoric/documentation/blob/main/main/reference/repl/networking.md
-->

Ideally, the example code in the README would be tested, but meanwhile, tests for open / initiate / send / close are in packages/vats/test/test-network.js. I added a bit of logging in 3d13c09 to make that explicit:

$ yarn test test/test-network.js 
...
  ✔ network - ibc
    ℹ Opening a Listening Port
    ℹ Accepting an Inbound Connection
    ℹ Sending Data - echo
    ℹ Receiving Data hello198
    ℹ Closing the Connection
    ℹ Connecting to a Remote Port
    ℹ Sending Data - transfer
    ℹ Receiving Data inbound-msg

We punted these from the critical path:

@dckc dckc closed this as completed Apr 22, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request needs-design
Projects
None yet
Development

No branches or pull requests

1 participant