ComputerSurge/shields
3
0
Fork 0
Code Pull Requests 1 Activity
Files
gh-pages
shields/module-core_token-pooling_token-pool-TokenPool.html
github-merge-queue[bot] 9b39b64f79 Deploying to gh-pages from @ badges/shields@9ac31b619a 🚀
2025-03-28 18:26:12 +00:00

908 lines
19 KiB
HTML
Raw Permalink Blame History

<!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#line174">line 174</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#line218">line 218</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="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#line325">line 325</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; {<a href="module-core_token-pooling_token-pool-Token.html">module:core/token-pooling/token-pool~Token</a>}</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#line300">line 300</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"><a href="module-core_token-pooling_token-pool-Token.html">module:core/token-pooling/token-pool~Token</a></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; {<a href="module-core_token-pooling_token-pool-Token.html">module:core/token-pooling/token-pool~Token</a>}</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"><a href="module-core_token-pooling_token-pool-Token.html">module:core/token-pooling/token-pool~Token</a></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"><a href="module-core_token-pooling_token-pool-Token.html">module:core/token-pooling/token-pool~Token</a></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#line202">line 202</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"><a href="module-core_token-pooling_token-pool-Token.html">module:core/token-pooling/token-pool~Token</a></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-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_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_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-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-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-Deprecated.html">Deprecated</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-urls.html">badge-urls</a></li><li><a href="tutorial-code-walkthrough.html">code-walkthrough</a></li><li><a href="tutorial-deprecating-badges.html">deprecating-badges</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-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><li><a href="tutorial-static-badges.html">static-badges</a></li></ul><h3>Global</h3><ul><li><a href="global.html#createNumRequestCounter">createNumRequestCounter</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#getBadgeExampleCall">getBadgeExampleCall</a></li><li><a href="global.html#getServiceClassAuthOrigin">getServiceClassAuthOrigin</a></li><li><a href="global.html#isMetricWithPattern">isMetricWithPattern</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.4</a> on Fri Mar 28 2025 18:26:11 GMT+0000 (Coordinated Universal Time)
</footer>
<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>
View Git Blame Copy Permalink