Files
shields/module-core_token-pooling_token-pool-TokenPool.html
T

1256 lines
23 KiB
HTML

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>JSDoc: Class: TokenPool</title>
<script src="scripts/prettify/prettify.js"> </script>
<script src="scripts/prettify/lang-css.js"> </script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
<link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>
<body>
<div id="main">
<h1 class="page-title">Class: TokenPool</h1>
<section>
<header>
<h2><span class="attribs"><span class="type-signature"></span></span>
<span class="ancestors"><a href="module-core_token-pooling_token-pool.html">core/token-pooling/token-pool</a>~</span>TokenPool<span class="signature">(batchSize)</span><span class="type-signature"></span></h2>
<div class="class-description"><p>Encapsulate a collection of rate-limited tokens and choose the next
available token when one is needed.</p>
<p>Designed for the Github API, though may be also useful with other rate-
limited APIs.</p></div>
</header>
<article>
<div class="container-overview">
<h2>Constructor</h2>
<h4 class="name" id="TokenPool"><span class="type-signature"></span>new TokenPool<span class="signature">(batchSize)</span><span class="type-signature"></span></h4>
<div class="description">
<p>TokenPool Constructor</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>batchSize</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last"><p>The maximum number of times we use each token before moving
on to the next one.</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="core_token-pooling_token-pool.js.html">core/token-pooling/token-pool.js</a>, <a href="core_token-pooling_token-pool.js.html#line196">line 196</a>
</li></ul></dd>
</dl>
</div>
<h3 class="subsection-title">Methods</h3>
<h4 class="name" id="add"><span class="type-signature"></span>add<span class="signature">(id, data, usesRemaining, nextReset)</span><span class="type-signature"> &rarr; {boolean}</span></h4>
<div class="description">
<p>Add a token with user-provided ID and data.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>id</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"><p>token string</p></td>
</tr>
<tr>
<td class="name"><code>data</code></td>
<td class="type">
<span class="param-type">*</span>
</td>
<td class="description last"><p>reserved for future use</p></td>
</tr>
<tr>
<td class="name"><code>usesRemaining</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last"><p>Number of uses remaining until the token is exhausted</p></td>
</tr>
<tr>
<td class="name"><code>nextReset</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last"><p>Time when the token can be used again even if it's exhausted (unix timestamp)</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="core_token-pooling_token-pool.js.html">core/token-pooling/token-pool.js</a>, <a href="core_token-pooling_token-pool.js.html#line240">line 240</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Was the token added to the pool?</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">boolean</span>
</dd>
</dl>
<h4 class="name" id="endBatchFor"><span class="type-signature"></span>endBatchFor<span class="signature">(token)</span><span class="type-signature"></span></h4>
<div class="description">
<p>Abandon the current batch if it belongs to <code>token</code>, so that the next call
to <code>next()</code> rotates to a different token. The token stays in the rotation
(it was already returned to the FIFO queue when its batch began) and is
retried when it next reaches the front of the queue.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>token</code></td>
<td class="type">
<span class="param-type">Token</span>
</td>
<td class="description last"><p>the token whose batch should be ended</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="core_token-pooling_token-pool.js.html">core/token-pooling/token-pool.js</a>, <a href="core_token-pooling_token-pool.js.html#line350">line 350</a>
</li></ul></dd>
</dl>
<h4 class="name" id="forEach"><span class="type-signature"></span>forEach<span class="signature">(callback)</span><span class="type-signature"></span></h4>
<div class="description">
<p>Iterate over all valid tokens.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>callback</code></td>
<td class="type">
<span class="param-type">function</span>
</td>
<td class="description last"><p>function to execute on each valid token</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="core_token-pooling_token-pool.js.html">core/token-pooling/token-pool.js</a>, <a href="core_token-pooling_token-pool.js.html#line361">line 361</a>
</li></ul></dd>
</dl>
<h4 class="name" id="next"><span class="type-signature"></span>next<span class="signature">()</span><span class="type-signature"> &rarr; {Token}</span></h4>
<div class="description">
<p>Obtain the next available token, returning <code>null</code> if no tokens are
available.</p>
<p>Tokens are initially pulled from a FIFO queue. The first token is used
for a batch of requests, then returned to the queue to give those
requests the opportunity to complete. The next token is used for the next
batch of requests.</p>
<p>This strategy allows a token to be used for concurrent requests, not just
sequential request, and simplifies token recovery after errored and timed
out requests.</p>
<p>By the time the original token re-emerges, its requests should have long
since completed. Even if a couple them are still running, they can
reasonably be ignored. The uses remaining won't be 100% correct, but
that's fine, because Shields uses only 75%</p>
<p>The process continues until an exhausted token is pulled from the FIFO
queue. At that time it's placed in the priority queue based on its
scheduled reset time. To ensure the priority queue works as intended,
the scheduled reset time is frozen then.</p>
<p>After obtaining a token using <code>next()</code>, invoke <code>update()</code> on it to set a
new use-remaining count and next-reset time. Invoke <code>invalidate()</code> to
indicate it should not be reused.</p>
</div>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="core_token-pooling_token-pool.js.html">core/token-pooling/token-pool.js</a>, <a href="core_token-pooling_token-pool.js.html#line322">line 322</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>token</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Token</span>
</dd>
</dl>
<h4 class="name" id="serializeDebugInfo"><span class="type-signature"></span>serializeDebugInfo<span class="signature">(options)</span><span class="type-signature"> &rarr; {object}</span></h4>
<div class="description">
<p>Serialize debug information about the token pool.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>options</code></td>
<td class="type">
<span class="param-type">object</span>
</td>
<td class="description last"><p>Options object</p>
<h6>Properties</h6>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>sanitize</code></td>
<td class="type">
<span class="param-type">boolean</span>
</td>
<td class="description last"><p>Whether to sanitize token IDs (default: true)</p></td>
</tr>
</tbody>
</table>
</td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="core_token-pooling_token-pool.js.html">core/token-pooling/token-pool.js</a>, <a href="core_token-pooling_token-pool.js.html#line379">line 379</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Debug information about the token pool</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">object</span>
</dd>
</dl>
<h4 class="name" id=".compareTokens"><span class="type-signature">(static) </span>compareTokens<span class="signature">(first, second)</span><span class="type-signature"> &rarr; {Token}</span></h4>
<div class="description">
<p>compareTokens</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>first</code></td>
<td class="type">
<span class="param-type">Token</span>
</td>
<td class="description last"><p>first token to compare</p></td>
</tr>
<tr>
<td class="name"><code>second</code></td>
<td class="type">
<span class="param-type">Token</span>
</td>
<td class="description last"><p>second token to compare</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="core_token-pooling_token-pool.js.html">core/token-pooling/token-pool.js</a>, <a href="core_token-pooling_token-pool.js.html#line224">line 224</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>The token whose current rate allotment is expiring soonest.</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Token</span>
</dd>
</dl>
</article>
</section>
</div>
<nav>
<h2><a href="index.html">Home</a></h2><h3>Modules</h3><ul><li><a href="module-badge-maker.html">badge-maker</a></li><li><a href="module-badge-maker_lib_xml.html">badge-maker/lib/xml</a></li><li><a href="module-core_base-service_base.html">core/base-service/base</a></li><li><a href="module-core_base-service_base-graphql.html">core/base-service/base-graphql</a></li><li><a href="module-core_base-service_base-json.html">core/base-service/base-json</a></li><li><a href="module-core_base-service_base-jsonl.html">core/base-service/base-jsonl</a></li><li><a href="module-core_base-service_base-svg-scraping.html">core/base-service/base-svg-scraping</a></li><li><a href="module-core_base-service_base-toml.html">core/base-service/base-toml</a></li><li><a href="module-core_base-service_base-xml.html">core/base-service/base-xml</a></li><li><a href="module-core_base-service_base-yaml.html">core/base-service/base-yaml</a></li><li><a href="module-core_base-service_check-error-response.html">core/base-service/check-error-response</a></li><li><a href="module-core_base-service_errors.html">core/base-service/errors</a></li><li><a href="module-core_base-service_graphql.html">core/base-service/graphql</a></li><li><a href="module-core_base-service_openapi.html">core/base-service/openapi</a></li><li><a href="module-core_base-service_resource-cache.html">core/base-service/resource-cache</a></li><li><a href="module-core_base-service_service-definitions.html">core/base-service/service-definitions</a></li><li><a href="module-core_server_server.html">core/server/server</a></li><li><a href="module-core_service-test-runner_create-service-tester.html">core/service-test-runner/create-service-tester</a></li><li><a href="module-core_service-test-runner_icedfrisby-shields.html">core/service-test-runner/icedfrisby-shields</a></li><li><a href="module-core_service-test-runner_runner.html">core/service-test-runner/runner</a></li><li><a href="module-core_service-test-runner_service-tester.html">core/service-test-runner/service-tester</a></li><li><a href="module-core_service-test-runner_services-for-title.html">core/service-test-runner/services-for-title</a></li><li><a href="module-core_token-pooling_token-pool.html">core/token-pooling/token-pool</a></li><li><a href="module-services_build-status.html">services/build-status</a></li><li><a href="module-services_color-formatters.html">services/color-formatters</a></li><li><a href="module-services_contributor-count.html">services/contributor-count</a></li><li><a href="module-services_date.html">services/date</a></li><li><a href="module-services_downloads.html">services/downloads</a></li><li><a href="module-services_dynamic-common.html">services/dynamic-common</a></li><li><a href="module-services_dynamic_json-path.html">services/dynamic/json-path</a></li><li><a href="module-services_endpoint-common.html">services/endpoint-common</a></li><li><a href="module-services_licenses.html">services/licenses</a></li><li><a href="module-services_package-json-helpers.html">services/package-json-helpers</a></li><li><a href="module-services_php-version.html">services/php-version</a></li><li><a href="module-services_pipenv-helpers.html">services/pipenv-helpers</a></li><li><a href="module-services_route-builder.html">services/route-builder</a></li><li><a href="module-services_size.html">services/size</a></li><li><a href="module-services_steam_steam-base.html">services/steam/steam-base</a></li><li><a href="module-services_test-results.html">services/test-results</a></li><li><a href="module-services_test-validators.html">services/test-validators</a></li><li><a href="module-services_text-formatters.html">services/text-formatters</a></li><li><a href="module-services_validators.html">services/validators</a></li><li><a href="module-services_version.html">services/version</a></li><li><a href="module-services_website-status.html">services/website-status</a></li><li><a href="module-services_winget_version.html">services/winget/version</a></li></ul><h3>Classes</h3><ul><li><a href="BaseThunderstoreService.html">BaseThunderstoreService</a></li><li><a href="module.html#.exports">exports</a></li><li><a href="module-badge-maker_lib_xml.ElementList.html">ElementList</a></li><li><a href="module-badge-maker_lib_xml.XmlElement.html">XmlElement</a></li><li><a href="module-core_base-service_base-graphql-BaseGraphqlService.html">BaseGraphqlService</a></li><li><a href="module-core_base-service_base-jsonl-BaseJsonlService.html">BaseJsonlService</a></li><li><a href="module-core_base-service_base-json-BaseJsonService.html">BaseJsonService</a></li><li><a href="module-core_base-service_base-svg-scraping-BaseSvgScrapingService.html">BaseSvgScrapingService</a></li><li><a href="module-core_base-service_base-toml-BaseTomlService.html">BaseTomlService</a></li><li><a href="module-core_base-service_base-xml-BaseXmlService.html">BaseXmlService</a></li><li><a href="module-core_base-service_base-yaml-BaseYamlService.html">BaseYamlService</a></li><li><a href="module-core_base-service_base-BaseService.html">BaseService</a></li><li><a href="module-core_base-service_errors-ImproperlyConfigured.html">ImproperlyConfigured</a></li><li><a href="module-core_base-service_errors-Inaccessible.html">Inaccessible</a></li><li><a href="module-core_base-service_errors-InvalidParameter.html">InvalidParameter</a></li><li><a href="module-core_base-service_errors-InvalidResponse.html">InvalidResponse</a></li><li><a href="module-core_base-service_errors-NotFound.html">NotFound</a></li><li><a href="module-core_base-service_errors-ShieldsRuntimeError.html">ShieldsRuntimeError</a></li><li><a href="module-core_server_server-Server.html">Server</a></li><li><a href="module-core_service-test-runner_runner-Runner.html">Runner</a></li><li><a href="module-core_service-test-runner_service-tester-ServiceTester.html">ServiceTester</a></li><li><a href="module-core_token-pooling_token-pool-Token.html">Token</a></li><li><a href="module-core_token-pooling_token-pool-TokenPool.html">TokenPool</a></li><li><a href="module-services_route-builder.html">services/route-builder</a></li><li><a href="module-services_steam_steam-base-BaseSteamAPI.html">BaseSteamAPI</a></li></ul><h3>Tutorials</h3><ul><li><a href="tutorial-TUTORIAL.html">TUTORIAL</a></li><li><a href="tutorial-adding-new-config-values.html">adding-new-config-values</a></li><li><a href="tutorial-authentication.html">authentication</a></li><li><a href="tutorial-badge-redirectors.html">badge-redirectors</a></li><li><a href="tutorial-badge-urls.html">badge-urls</a></li><li><a href="tutorial-code-walkthrough.html">code-walkthrough</a></li><li><a href="tutorial-input-validation.html">input-validation</a></li><li><a href="tutorial-json-format.html">json-format</a></li><li><a href="tutorial-performance-testing.html">performance-testing</a></li><li><a href="tutorial-production-hosting.html">production-hosting</a></li><li><a href="tutorial-releases.html">releases</a></li><li><a href="tutorial-retiring-badges.html">retiring-badges</a></li><li><a href="tutorial-self-hosting.html">self-hosting</a></li><li><a href="tutorial-server-secrets.html">server-secrets</a></li><li><a href="tutorial-service-tests.html">service-tests</a></li></ul><h3>Global</h3><ul><li><a href="global.html#_formatLabelForStage">_formatLabelForStage</a></li><li><a href="global.html#assert">assert</a></li><li><a href="global.html#createNumRequestCounter">createNumRequestCounter</a></li><li><a href="global.html#escapeFormat">escapeFormat</a></li><li><a href="global.html#fakeJwtToken">fakeJwtToken</a></li><li><a href="global.html#generateFakeConfig">generateFakeConfig</a></li><li><a href="global.html#generateInstanceId">generateInstanceId</a></li><li><a href="global.html#getBadgeExampleCall">getBadgeExampleCall</a></li><li><a href="global.html#getServiceClassAuthOrigin">getServiceClassAuthOrigin</a></li><li><a href="global.html#getUserAgent">getUserAgent</a></li><li><a href="global.html#legacySonarResponse">legacySonarResponse</a></li><li><a href="global.html#logTrace">logTrace</a></li><li><a href="global.html#noteGithubTokenInvalidation">noteGithubTokenInvalidation</a></li><li><a href="global.html#parseJson">parseJson</a></li><li><a href="global.html#parseJsonl">parseJsonl</a></li><li><a href="global.html#rasterRedirectUrl">rasterRedirectUrl</a></li><li><a href="global.html#testAuth">testAuth</a></li></ul>
</nav>
<br class="clear">
<footer>
Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 4.0.5</a> on Thu Jul 16 2026 07:59:17 GMT+0000 (Coordinated Universal Time)
</footer>
<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>