From 048d344e2286f6f9ca4a847159c9a2e96f38f48d Mon Sep 17 00:00:00 2001 From: Turadg Aleahmad Date: Tue, 30 Apr 2024 11:35:51 -0700 Subject: [PATCH] feat(types): export explicit types --- packages/network/src/bytes.js | 4 ++ packages/network/src/index.js | 1 + packages/network/src/network.js | 47 +++++++++++-------- packages/network/src/router.js | 4 ++ packages/network/src/types.js | 3 ++ packages/network/test/test-network-misc.js | 4 +- packages/orchestration/src/service.js | 5 +- .../vats/src/proposals/network-proposal.js | 5 ++ 8 files changed, 51 insertions(+), 22 deletions(-) diff --git a/packages/network/src/bytes.js b/packages/network/src/bytes.js index f37082127bcf..547d0dd5cd85 100644 --- a/packages/network/src/bytes.js +++ b/packages/network/src/bytes.js @@ -3,6 +3,10 @@ import { Fail } from '@agoric/assert'; import { encodeBase64, decodeBase64 } from '@endo/base64'; +/** + * @import {Bytes} from './types.js'; + */ + /** @typedef {Bytes | Buffer | Uint8Array | Iterable} ByteSource */ /** diff --git a/packages/network/src/index.js b/packages/network/src/index.js index 2bf1e45eacdc..9b967d67ea16 100644 --- a/packages/network/src/index.js +++ b/packages/network/src/index.js @@ -3,3 +3,4 @@ export * from './shapes.js'; export { prepareRouter, prepareRouterProtocol } from './router.js'; export * from './multiaddr.js'; export * from './bytes.js'; +export * from './types.js'; diff --git a/packages/network/src/network.js b/packages/network/src/network.js index 2a09b56b33e6..a5d4136ae10e 100644 --- a/packages/network/src/network.js +++ b/packages/network/src/network.js @@ -8,6 +8,9 @@ import { Shape } from './shapes.js'; import '@agoric/store/exported.js'; /// +/** + * @import {AttemptDescription, Bytes, Closable, CloseReason, Connection, ConnectionHandler, Endpoint, ListenHandler, Port, Protocol, ProtocolHandler, ProtocolImpl} from './types.js'; + */ /** * Compatibility note: this must match what our peers use, so don't change it @@ -409,7 +412,7 @@ const preparePort = (zone, powers) => { * @param {MapStore>} opts.currentConnections * @param {MapStore} opts.boundPorts * @param {import('@agoric/vow').Remote} opts.protocolHandler - * @param {Remote} opts.protocolImpl + * @param {import('@agoric/vow').Remote} opts.protocolImpl */ const initPort = ({ localAddr, @@ -454,7 +457,9 @@ const preparePort = (zone, powers) => { } listening.set(localAddr, [ this.facets.port, - /** @type {Remote>} */ (listenHandler), + /** @type {import('@agoric/vow').Remote>} */ ( + listenHandler + ), ]); E(lhandler).onRemove(lport, lhandler).catch(rethrowUnlessMissing); } else { @@ -462,7 +467,9 @@ const preparePort = (zone, powers) => { localAddr, harden([ this.facets.port, - /** @type {Remote>} */ (listenHandler), + /** @type {import('@agoric/vow').Remote>} */ ( + listenHandler + ), ]), ); } @@ -481,7 +488,7 @@ const preparePort = (zone, powers) => { ); return watch(innerVow, this.facets.rethrowUnlessMissingWatcher); }, - /** @param {Remote} listenHandler */ + /** @param {import('@agoric/vow').Remote} listenHandler */ async removeListener(listenHandler) { const { listening, localAddr, protocolHandler } = this.state; listening.has(localAddr) || Fail`Port ${localAddr} is not listening`; @@ -503,11 +510,11 @@ const preparePort = (zone, powers) => { }, /** * @param {Endpoint} remotePort - * @param {Remote} [connectionHandler] + * @param {import('@agoric/vow').Remote} [connectionHandler] */ async connect( remotePort, - connectionHandler = /** @type {Remote} */ ( + connectionHandler = /** @type {import('@agoric/vow').Remote} */ ( makeIncapable() ), ) { @@ -724,8 +731,8 @@ const prepareBinder = (zone, powers) => { * @param {object} opts * @param {MapStore>} opts.currentConnections * @param {MapStore} opts.boundPorts - * @param {MapStore>]>} opts.listening - * @param {Remote} opts.protocolHandler + * @param {MapStore>]>} opts.listening + * @param {import('@agoric/vow').Remote} opts.protocolHandler */ ({ currentConnections, boundPorts, listening, protocolHandler }) => { /** @type {SetStore} */ @@ -771,7 +778,7 @@ const prepareBinder = (zone, powers) => { const innerVow = watch( E( - /** @type {Remote>} */ ( + /** @type {import('@agoric/vow').Remote>} */ ( protocolHandler ), ).onInstantiate( @@ -813,7 +820,7 @@ const prepareBinder = (zone, powers) => { // Allocate a local address. const instantiateInnerVow = watch( E( - /** @type {Remote>} */ ( + /** @type {import('@agoric/vow').Remote>} */ ( protocolHandler ), ).onInstantiate(port, localAddr, remoteAddr, protocolHandler), @@ -939,7 +946,7 @@ const prepareBinder = (zone, powers) => { const innerVow = watch( E( - /** @type {Remote>} */ ( + /** @type {import('@agoric/vow').Remote>} */ ( protocolHandler ), ).onInstantiate( @@ -1169,7 +1176,7 @@ export const prepareNetworkProtocol = (zone, powers) => { const makeBinderKit = prepareBinder(zone, powers); /** - * @param {Remote} protocolHandler + * @param {import('@agoric/vow').Remote} protocolHandler * @returns {Protocol} */ const makeNetworkProtocol = protocolHandler => { @@ -1181,7 +1188,7 @@ export const prepareNetworkProtocol = (zone, powers) => { /** @type {MapStore} */ const boundPorts = detached.mapStore('addrToPort'); - /** @type {MapStore>]>} */ + /** @type {MapStore>]>} */ const listening = detached.mapStore('listening'); const { binder, protocolImpl } = makeBinderKit({ @@ -1293,7 +1300,7 @@ export function prepareLoopbackProtocolHandler(zone, { watch, allVows }) { /** @param {string} [instancePrefix] */ const initHandler = (instancePrefix = 'nonce/') => { - /** @type {MapStore, Remote>]>} */ + /** @type {MapStore, import('@agoric/vow').Remote>]>} */ const listeners = detached.mapStore('localAddr'); return { @@ -1325,7 +1332,7 @@ export function prepareLoopbackProtocolHandler(zone, { watch, allVows }) { * @param {*} _port * @param {Endpoint} localAddr * @param {Endpoint} remoteAddr - * @returns {PromiseVow}} + * @returns {import('@agoric/vow').PromiseVow}} */ async onConnect(_port, localAddr, remoteAddr) { const { listeners } = this.state; @@ -1372,7 +1379,7 @@ export function prepareLoopbackProtocolHandler(zone, { watch, allVows }) { localAddr, harden([ port, - /** @type {Remote>} */ ( + /** @type {import('@agoric/vow').Remote>} */ ( listenHandler ), ]), @@ -1383,15 +1390,17 @@ export function prepareLoopbackProtocolHandler(zone, { watch, allVows }) { localAddr, harden([ port, - /** @type {Remote>} */ (listenHandler), + /** @type {import('@agoric/vow').Remote>} */ ( + listenHandler + ), ]), ); } }, /** - * @param {Remote} port + * @param {import('@agoric/vow').Remote} port * @param {Endpoint} localAddr - * @param {Remote} listenHandler + * @param {import('@agoric/vow').Remote} listenHandler * @param {*} _protocolHandler */ async onListenRemove(port, localAddr, listenHandler, _protocolHandler) { diff --git a/packages/network/src/router.js b/packages/network/src/router.js index 27de1036b0a5..477a23f4f35d 100644 --- a/packages/network/src/router.js +++ b/packages/network/src/router.js @@ -8,6 +8,10 @@ import { Shape } from './shapes.js'; // XXX ambient types runtime imports until https://github.com/Agoric/agoric-sdk/issues/6512 import '@agoric/store/exported.js'; /// +/** + * @import {AttemptDescription, Bytes, Closable, CloseReason, Connection, ConnectionHandler, Endpoint, ListenHandler, Port, Protocol, ProtocolHandler, ProtocolImpl} from './types.js'; + * @import {PromiseVow, Remote, VowKit, VowResolver, VowTools} from '@agoric/vow'; + */ /** * @template T diff --git a/packages/network/src/types.js b/packages/network/src/types.js index 43e0e90c3661..204a8a4fcaf5 100644 --- a/packages/network/src/types.js +++ b/packages/network/src/types.js @@ -1,5 +1,8 @@ // @ts-check +// Ensure this is a module. +export {}; + /** @import {PromiseVow, Remote} from '@agoric/vow' */ /** diff --git a/packages/network/test/test-network-misc.js b/packages/network/test/test-network-misc.js index 9c23e443b4d2..e406e720f16e 100644 --- a/packages/network/test/test-network-misc.js +++ b/packages/network/test/test-network-misc.js @@ -17,7 +17,9 @@ import { preparePortAllocator, } from '../src/index.js'; -import '../src/types.js'; +/** + * @import {ListenHandler} from '../src/types.js'; + */ // eslint-disable-next-line no-constant-condition const log = false ? console.log : () => {}; diff --git a/packages/orchestration/src/service.js b/packages/orchestration/src/service.js index 55e7f6329221..a4443dd665d1 100644 --- a/packages/orchestration/src/service.js +++ b/packages/orchestration/src/service.js @@ -14,11 +14,12 @@ import { makeICAConnectionAddress, parseAddress } from './utils/address.js'; import { makeTxPacket, parsePacketAck } from './utils/tx.js'; /** - * @import { ChainAccount, ChainAddress } from './types.js'; + * @import {Connection, Port, PortAllocator} from '@agoric/network'; + * @import {Remote} from '@agoric/vow'; * @import { IBCConnectionID } from '@agoric/vats'; * @import { Zone } from '@agoric/base-zone'; * @import { TxBody } from '@agoric/cosmic-proto/cosmos/tx/v1beta1/tx.js'; - * + * @import { AttenuatedNetwork, ChainAccount, ChainAddress } from './types.js'; */ const { Fail, bare } = assert; diff --git a/packages/vats/src/proposals/network-proposal.js b/packages/vats/src/proposals/network-proposal.js index 7b88b855ae4a..cd3f2587bb9b 100644 --- a/packages/vats/src/proposals/network-proposal.js +++ b/packages/vats/src/proposals/network-proposal.js @@ -11,6 +11,11 @@ import { makeScalarBigMapStore } from '@agoric/vat-data'; // bootstrap vat can't yet be upgraded. import { when } from '@agoric/vat-data/vow.js'; +/** + * @import {ProtocolHandler} from '@agoric/network'; + * @import {Remote} from '@agoric/vow'; + */ + const NUM_IBC_PORTS_PER_CLIENT = 3; /**