@ar.io/wayfinder-core 1.2.0 → 1.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +110 -0
- package/dist/routing/ping.d.ts.map +1 -1
- package/dist/routing/ping.js +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/dist/wayfinder.d.ts.map +1 -1
- package/dist/wayfinder.js +1 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -216,6 +216,114 @@ const routingStrategy = new PreferredWithFallbackRoutingStrategy({
|
|
|
216
216
|
});
|
|
217
217
|
```
|
|
218
218
|
|
|
219
|
+
### Strategy Composition Examples
|
|
220
|
+
|
|
221
|
+
Here are a few “lego-style” examples showing how existing routing strategies can
|
|
222
|
+
be composed to suit different use cases. Each strategy implements
|
|
223
|
+
`RoutingStrategy`, so they can be wrapped and combined freely.
|
|
224
|
+
|
|
225
|
+
#### Random + Ping health checks
|
|
226
|
+
|
|
227
|
+
Pick a random gateway, then verify it responds with a `HEAD` request before
|
|
228
|
+
returning it.
|
|
229
|
+
|
|
230
|
+
```ts
|
|
231
|
+
import {
|
|
232
|
+
RandomRoutingStrategy,
|
|
233
|
+
PingRoutingStrategy,
|
|
234
|
+
} from "@ar.io/wayfinder-core";
|
|
235
|
+
|
|
236
|
+
const strategy = new PingRoutingStrategy({
|
|
237
|
+
routingStrategy: new RandomRoutingStrategy(),
|
|
238
|
+
retries: 2,
|
|
239
|
+
timeoutMs: 500,
|
|
240
|
+
});
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
#### Fastest ping wrapped with a simple cache
|
|
244
|
+
|
|
245
|
+
Find the lowest-latency gateway and cache the result for five minutes to avoid
|
|
246
|
+
constant pings.
|
|
247
|
+
|
|
248
|
+
```ts
|
|
249
|
+
import {
|
|
250
|
+
FastestPingRoutingStrategy,
|
|
251
|
+
SimpleCacheRoutingStrategy,
|
|
252
|
+
} from "@ar.io/wayfinder-core";
|
|
253
|
+
|
|
254
|
+
const strategy = new SimpleCacheRoutingStrategy({
|
|
255
|
+
routingStrategy: new FastestPingRoutingStrategy({ timeoutMs: 500 }),
|
|
256
|
+
ttlSeconds: 300,
|
|
257
|
+
});
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
#### Preferred gateway with fallback to ping-random
|
|
261
|
+
|
|
262
|
+
Attempt to use a favorite gateway, but fall back to a ping-checked random choice
|
|
263
|
+
if it fails.
|
|
264
|
+
|
|
265
|
+
```ts
|
|
266
|
+
import {
|
|
267
|
+
PreferredWithFallbackRoutingStrategy,
|
|
268
|
+
RandomRoutingStrategy,
|
|
269
|
+
PingRoutingStrategy,
|
|
270
|
+
} from "@ar.io/wayfinder-core";
|
|
271
|
+
|
|
272
|
+
const strategy = new PreferredWithFallbackRoutingStrategy({
|
|
273
|
+
preferredGateway: "https://my-gateway.example",
|
|
274
|
+
fallbackStrategy: new PingRoutingStrategy({
|
|
275
|
+
routingStrategy: new RandomRoutingStrategy(),
|
|
276
|
+
}),
|
|
277
|
+
});
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
#### Round-robin + ping verification
|
|
281
|
+
|
|
282
|
+
Cycle through gateways sequentially, checking each one’s health before use.
|
|
283
|
+
|
|
284
|
+
```ts
|
|
285
|
+
import {
|
|
286
|
+
RoundRobinRoutingStrategy,
|
|
287
|
+
PingRoutingStrategy,
|
|
288
|
+
} from "@ar.io/wayfinder-core";
|
|
289
|
+
|
|
290
|
+
const strategy = new PingRoutingStrategy({
|
|
291
|
+
routingStrategy: new RoundRobinRoutingStrategy({
|
|
292
|
+
gateways: [new URL("https://gw1"), new URL("https://gw2")],
|
|
293
|
+
}),
|
|
294
|
+
});
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
#### Cache around any composed strategy
|
|
298
|
+
|
|
299
|
+
Because `SimpleCacheRoutingStrategy` accepts any `RoutingStrategy`, you can
|
|
300
|
+
cache more complex compositions too.
|
|
301
|
+
|
|
302
|
+
```ts
|
|
303
|
+
const pingRandom = new PingRoutingStrategy({
|
|
304
|
+
routingStrategy: new RandomRoutingStrategy(),
|
|
305
|
+
});
|
|
306
|
+
|
|
307
|
+
const cachedStrategy = new SimpleCacheRoutingStrategy({
|
|
308
|
+
routingStrategy: pingRandom,
|
|
309
|
+
ttlSeconds: 600,
|
|
310
|
+
});
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
In all cases, you can supply the composed strategy to `Wayfinder` (or whatever
|
|
314
|
+
router factory you use) and pass in a gateways provider:
|
|
315
|
+
|
|
316
|
+
```ts
|
|
317
|
+
import { Wayfinder, StaticGatewaysProvider } from "@ar.io/wayfinder-core";
|
|
318
|
+
|
|
319
|
+
const router = new Wayfinder({
|
|
320
|
+
gatewaysProvider: new StaticGatewaysProvider({
|
|
321
|
+
gateways: [new URL("https://gw1"), new URL("https://gw2")],
|
|
322
|
+
}),
|
|
323
|
+
routingStrategy: strategy, // any of the compositions above
|
|
324
|
+
});
|
|
325
|
+
```
|
|
326
|
+
|
|
219
327
|
## Verification Strategies
|
|
220
328
|
|
|
221
329
|
Wayfinder includes verification mechanisms to ensure the integrity of retrieved data. Verification strategies offer different trade-offs between complexity, performance, and security.
|
|
@@ -489,6 +597,8 @@ const wayfinder = new Wayfinder({
|
|
|
489
597
|
enabled: true, // disabled by default (must be explicitly enabled)
|
|
490
598
|
sampleRate: 0.1, // 10% sample rate by default
|
|
491
599
|
exporterUrl: 'https://your-custom-otel-exporter', // optional, defaults to https://api.honeycomb.io/v1/traces
|
|
600
|
+
clientName: 'my-custom-client-name', // optional, defaults to wayfinder-core
|
|
601
|
+
clientVersion: '1.0.0', // optional, defaults to empty
|
|
492
602
|
},
|
|
493
603
|
});
|
|
494
604
|
```
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ping.d.ts","sourceRoot":"","sources":["../../src/routing/ping.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE3D,qBAAa,0BAA2B,YAAW,eAAe;IAChE,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,cAAc,CAAS;gBAEnB,EACV,SAAe,EACf,cAAmB,EACnB,MAAsB,GACvB,GAAE;QACD,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,MAAM,CAAC;KACZ;IAMA,aAAa,CAAC,EAClB,QAAQ,EACR,IAAS,EACT,SAAS,GACV,EAAE;QACD,QAAQ,EAAE,GAAG,EAAE,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,GAAG,CAAC;CA8EjB;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACzD,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAS;gBAEd,EACV,eAAe,EACf,MAAsB,EACtB,OAAW,EACX,
|
|
1
|
+
{"version":3,"file":"ping.d.ts","sourceRoot":"","sources":["../../src/routing/ping.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE3D,qBAAa,0BAA2B,YAAW,eAAe;IAChE,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,cAAc,CAAS;gBAEnB,EACV,SAAe,EACf,cAAmB,EACnB,MAAsB,GACvB,GAAE;QACD,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,MAAM,CAAC;KACZ;IAMA,aAAa,CAAC,EAClB,QAAQ,EACR,IAAS,EACT,SAAS,GACV,EAAE;QACD,QAAQ,EAAE,GAAG,EAAE,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,GAAG,CAAC;CA8EjB;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACzD,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAS;gBAEd,EACV,eAAe,EACf,MAAsB,EACtB,OAAW,EACX,SAAgB,GACjB,EAAE;QACD,eAAe,EAAE,eAAe,CAAC;QACjC,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB;IAOK,aAAa,CAAC,MAAM,EAAE;QAC1B,QAAQ,CAAC,EAAE,GAAG,EAAE,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,GAAG,CAAC;CAoEjB"}
|
package/dist/routing/ping.js
CHANGED
|
@@ -102,7 +102,7 @@ export class PingRoutingStrategy {
|
|
|
102
102
|
logger;
|
|
103
103
|
retries;
|
|
104
104
|
timeoutMs;
|
|
105
|
-
constructor({ routingStrategy, logger = defaultLogger, retries =
|
|
105
|
+
constructor({ routingStrategy, logger = defaultLogger, retries = 5, timeoutMs = 1000, }) {
|
|
106
106
|
this.routingStrategy = routingStrategy;
|
|
107
107
|
this.logger = logger;
|
|
108
108
|
this.retries = retries;
|
package/dist/version.d.ts
CHANGED
|
@@ -14,5 +14,5 @@
|
|
|
14
14
|
* See the License for the specific language governing permissions and
|
|
15
15
|
* limitations under the License.
|
|
16
16
|
*/
|
|
17
|
-
export declare const WAYFINDER_CORE_VERSION = "v1.2.
|
|
17
|
+
export declare const WAYFINDER_CORE_VERSION = "v1.2.1";
|
|
18
18
|
//# sourceMappingURL=version.d.ts.map
|
package/dist/version.js
CHANGED
package/dist/wayfinder.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"wayfinder.d.ts","sourceRoot":"","sources":["../src/wayfinder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAAQ,KAAK,MAAM,EAAkB,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAKhD,OAAO,KAAK,EACV,gBAAgB,EAChB,MAAM,EACN,eAAe,EACf,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAKpB,eAAO,MAAM,uBAAuB,GAAI,cAErC;IACD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;;;CAMA,CAAC;AAGF,eAAO,MAAM,SAAS,QAAuB,CAAC;AAC9C,eAAO,MAAM,SAAS,QAAwB,CAAC;AAE/C;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,kBAAkB,KACzB,YAoCF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAC7B,OAAO,MAAM,KACZ;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAqCnC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAAI,uCAIjC;IACD,eAAe,EAAE,GAAG,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd,KAAG,GAcH,CAAC;AAEF,wBAAgB,0BAA0B,CAAC,EACzC,cAAc,EACd,aAAa,EACb,UAAU,EACV,IAAI,EACJ,OAAO,EACP,OAAY,EACZ,MAAc,GACf,EAAE;IACD,cAAc,EAAE,cAAc,CAAC;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,UAAU,EAAE,oBAAoB,CAAC,YAAY,CAAC,CAAC;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,cAAc,CAkFjB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,GAAI,uFAO5B;IACD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,oBAAoB,EAAE,WAAW,CAAC,gBAAgB,CAAC,sBAAsB,CAAC,CAAC,CAAC;IAC5E,eAAe,EAAE,WAAW,CAAC,gBAAgB,CAAC,iBAAiB,CAAC,CAAC,CAAC;IAClE,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,MAEG,OAAO,GAAG,GAAG,WAAW,EACxB,OAAO,WAAW,GAAG;IACnB,oBAAoB,CAAC,EAAE,WAAW,CAChC,gBAAgB,CAAC,sBAAsB,CAAC,CACzC,CAAC;IACF,eAAe,CAAC,EAAE,WAAW,CAAC,gBAAgB,CAAC,iBAAiB,CAAC,CAAC,CAAC;CACpE,KACA,OAAO,CAAC,QAAQ,
|
|
1
|
+
{"version":3,"file":"wayfinder.d.ts","sourceRoot":"","sources":["../src/wayfinder.ts"],"names":[],"mappings":"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"}
|
package/dist/wayfinder.js
CHANGED
|
@@ -304,6 +304,7 @@ export const wayfinderFetch = ({ logger = defaultLogger, gatewaysProvider, verif
|
|
|
304
304
|
...restInit,
|
|
305
305
|
});
|
|
306
306
|
// add response attributes to the span
|
|
307
|
+
requestSpan?.setAttribute('response.url', redirectUrl.toString());
|
|
307
308
|
requestSpan?.setAttribute('response.status', response.status);
|
|
308
309
|
requestSpan?.setAttribute('response.statusText', response.statusText);
|
|
309
310
|
response.headers.forEach((value, key) => {
|