Repository navigation
add admin commands - #2219
Draft
alexcos20 wants to merge 1 commit into
Draft
add admin commands#2219alexcos20 wants to merge 1 commit into
alexcos20 wants to merge 1 commit into
Conversation
|
Important Draft PR not reviewedDraft PRs are not automatically reviewed by default.
To automatically review draft PRs, update your CodeRabbit configuration: reviews:
auto_review:
drafts: true
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Node admin methods on
ProviderInstance(every admin command over HTTP and P2P)Summary
Adds first-class client methods for every Ocean Node admin-gated protocol command, over both
transports (HTTP and P2P), each taking a
Signer(or, where the node allows it, an auth token) andsigning internally. Previously ocean.js fully covered only
getLogs(list) andsetMaintenance, andhalf-covered
fetchConfig/pushConfig(P2P-only, caller built and signed the payload).Callers now get one method per admin action, with the transport chosen automatically by
ProviderInstanceand the signature built internally — no hand-rolled signing, nonce handling, orpeerId resolution.
This branches off
feature/peerId_in_all_signatures(PR #2217) and inherits its peerId-boundsigning, so every new admin signature binds the target node's peerId with no extra code.
New API (
BaseProviderfacade →HttpProvider+P2pProvider)stopNode(nodeUri, signer, signal?)STOP_NODEPromise<void>adminStopJob(nodeUri, signer, jobId, signal?)STOP_JOB(new constant)jobIdPromise<any>reindexTx(nodeUri, signer, chainId, txId, signal?)REINDEX_TXchainId,txIdPromise<NodeAdminJobStatus>reindexChain(nodeUri, signer, chainId, block?, signal?)REINDEX_CHAINchainId,block?Promise<NodeAdminJobStatus>handleIndexingThread(nodeUri, signer, action, chainId?, signal?)HANDLE_INDEXING_THREADaction,chainId?Promise<void>collectFees(nodeUri, signer, params, signal?)COLLECT_FEESchainId,tokenAddress,destinationAddress,tokenAmount?Promise<CollectFeesResult>getNodeLog(nodeUri, signerOrToken, logId, signal?)GET_LOGSlogIdPromise<NodeLogEntry>getNodeConfig(nodeUri, signerOrToken, signal?)FETCH_CONFIGPromise<Record<string, any>>setNodeConfig(nodeUri, signer, config, signal?)PUSH_CONFIGconfigPromise<Record<string, any>>getNodeDetailedStatus(nodeUri, signal?)DETAILED_STATUSPromise<NodeStatus>The existing
fetchConfig/pushConfigare kept and marked@deprecatedin favour ofgetNodeConfig/setNodeConfig.Signing: inherited peerId binding (ocean-node #1619 / ocean.js #2217)
The admin methods reuse the single per-transport signing chokepoint,
getSignedCommandParams, so thesigned message is
address + nonce + command + issuerPeerIdwith the node's peerId resolvedautomatically (HTTP from
getNodeStatus(nodeUri).id; P2P from the peerId already innodeUri). Noadmin method builds a signature or the peerId binding by hand, and there is no empty-peerId fallback.
Auth tokens: read-only vs mutating split (ocean-node #1616)
The node now accepts scoped auth tokens only for the two read-only admin commands and keeps every
mutating admin command signature-only. The client enforces the same split up front:
stopNode,adminStopJob,reindexTx,reindexChain,handleIndexingThread,collectFees,setNodeConfig): a string auth token is rejected client-side byassertAdminSignerbefore any network call (no nonce lookup, no STATUS round-trip, no POST).getNodeConfig→FETCH_CONFIG,getNodeLog→GET_LOGS): accept a signer or aJWT. A token is sent in the
Authorizationheader (exactly asdownloadNodeLogsdoes) and thetoken path skips peerId resolution and signing.
This is implemented with a private
sendAdminCommand(…, allowAuthToken = false)helper in eachprovider —
allowAuthToken: trueis passed only bygetNodeConfig/getNodeLog.Types & constants (
src/@types/Provider.ts)PROTOCOL_COMMANDS.STOP_JOB = 'stopJob'added.IndexingThreadAction,NodeAdminJobStatus,CollectFeesParams,CollectFeesResult.NodeStatusgains optionalc2dClusters?,supportedSchemas?,authTokenPolicy?.Behaviour details enforced by the node (documented in JSDoc)
undefined/null—block: 0,chainId: 0andtokenAmount: 0are meaningful and ARE sent (no truthiness tests).tokenAmountis sent verbatim(the node scales it).
OceanNodeProviderError(withhttpStatus),P2P rejections as the already-thrown
P2pError— neither is converted to the other.stopNodeexits the node process;collectFeeswithouttokenAmountsweeps the whole balance;setNodeConfigshallow-merges and canreplace the
keysblock; over P2P a transport error afterstopNodecan mean the node alreadystopped.
Drive-by fix
HttpProvider.downloadNodeLogsbuilt its query string by unescaped concatenation. It now usesURLSearchParams(public parameter list and order unchanged), somoduleName/levelare properlyencoded. Covered by a new unit case (
moduleName: 'a b&c'→moduleName=a+b%26c).Tests
test/unit/AdminCommands.test.ts(new, no infra): 89 passing. Table-driven over allmethods on both transports. Asserts: the peerId-bound signed message
(
address + nonce + command + issuerPeerId, and that the old unbound message does not verify);no
nodefield in the body; the optional-param rules (including0); HTTP →OceanNodeProviderErrorand P2P →
P2pError; the auth-token split (mutating methods reject a token with zero fetches;read-only methods accept it via the
Authorizationheader with no signature);getNodeDetailedStatusunsigned; and transport dispatch for all ten methods.
test/unit/MaintenanceMode.test.ts: 24 passing, unchanged.test/integration/Provider.test.ts(addeddescribe): written but NOT run. Theyneed ocean-node PRs Bump vm2 from 3.9.9 to 3.9.11 #1616 and Bump typescript from 4.7.4 to 4.8.4 #1619 merged plus Barge, so they are intentionally left to run once
those land. They type-check (via
tsc --noEmitin lint). The suite resolves an admin signer from thenode's
allowedAdmins(falling back to the well-known Barge admin key) and skips cleanly otherwise;it never calls
stopNodeor a blocklessreindexChain(both would disrupt the shared node) — thosestay unit-only.
Docs
README.mdfeature list and a new "Node administration" section inCheatsheet.md. Generated files(
CHANGELOG.md,docs/,dist/lib.json) are untouched; the version is not bumped (release is themaintainer's step — this is an additive, minor-bump change).
Reconciliation with #2214 (scoped auth tokens)
#2214 and #2217 are siblings off
rc_11.0.0and do not contain each other; they conflict ongenerateAuthTokenandNodeStatus. This admin work currently sits on #2217. Once #2214 and #2217are merged together (so
generateAuthTokencarries both the peerId binding and the scoped-tokenoptions + OJ-03), this branch rebases onto that combined base and adapts as follows:
PROTOCOL_COMMANDS.STOP_JOBandNodeStatus.authTokenPolicy(Feat/scoped auth tokens #2214 types the latter asAuthTokenPolicy, notany). Keep ourc2dClusters/supportedSchemas.generateAuthToken(signer, url, { validUntil, scope })(the old 2-arg call throws once Feat/scoped auth tokens #2214lands), and the
it.skip('a token scoped to getLogs only is rejected by getNodeConfig')isun-skipped by minting a token scoped to
getLogsonly.CommandCatalog(adminReadonly/tokenAuthannotations) to drive theread-only vs mutating split instead of the hardcoded
allowAuthTokenflags — the catalog alreadymarks
fetchConfig/getLogsasadminReadonly+tokenAuthand the mutating admin commands asscope-disallowed.
The signature-building for the admin commands themselves is unaffected (they reuse
getSignedCommandParams, which both PRs leave as the chokepoint).Rollout
Ship after (or together with) ocean-node #1619 (universal peerId-bound signing) and #1616
(scoped auth tokens + read-only-admin token opt-in). An upgraded client talking to an old node (or
vice versa) mismatches on the signed message; the read-only auth-token integration cases are gated on
the node advertising
authTokenPolicyand skip against older nodes.