@effected/github 0.18.0 → 0.20.0

package/GitHubApp.js

@@ -4,7 +4,7 @@ import { GitHubClient, makeClientShape } from "./GitHubClient.js";
 import { numericId } from "./internal/ids.js";
 import { InstallationTokenStore } from "./InstallationTokenStore.js";
 import { Jwt, JwtKey } from "@effected/jwt";
-import { Cause, Clock, Context, DateTime, Duration, Effect, Layer, Option, Redacted, Ref, Schema, Semaphore, Stream } from "effect";
+import { Cause, Clock, Context, DateTime, Deferred, Duration, Effect, Layer, Option, Redacted, Ref, Schema, Semaphore, Stream } from "effect";
 
 //#region src/GitHubApp.ts
 /**
@@ -373,14 +373,23 @@ var GitHubApp = class GitHubApp extends Context.Service()("@effected/github/GitH
 	* **A cached token is never revoked**: another scope or isolate may be using
 	* it. It expires on its own, within the hour.
 	*
-	* Two concurrent calls that both miss will both mint, and the later write
-	* wins. That is expected: the store may span isolates, so the kit cannot
-	* lock it, and an extra token costs one call and expires on its own.
+	* Within one process, concurrent misses for one installation are
+	* **single-flight**: the first caller mints and the others wait for that
+	* mint and return the same token with `source: "joined"`, so a batch that
+	* fans out over one installation on a cold store costs one mint, not one
+	* per fiber. The in-flight record lives with the `GitHubApp` service and is
+	* released when the mint settles, however it settles: a failed mint fails
+	* every waiter with the same `GitHubAppError`, and the next call mints
+	* again. Interrupting the leader does not strand the waiters: the mint runs
+	* in its own fiber and completes for them. Across isolates, two misses
+	* still both mint and the later write wins. That is expected: the store may
+	* span isolates, so the kit cannot lock it, and an extra token costs one
+	* call and expires on its own.
 	*
 	* The encoded value written to the store contains the raw token, so
 	* encrypting it at rest is the store's job.
 	*/
-	static cachedToken = (request) => cachedTokenFor(request);
+	static cachedToken = (request) => Effect.flatMap(GitHubApp, (app) => app.cachedToken(request));
 	/**
 	* A {@link GitHubClient} authenticated with {@link GitHubApp.cachedToken}.
 	*
@@ -422,19 +431,23 @@ var GitHubApp = class GitHubApp extends Context.Service()("@effected/github/GitH
 	* Effect.runPromise(Effect.provide(handle(42), Live));
 	* ```
 	*/
-	static cachedClientLayer = (request, options = {}) => Layer.unwrap(Effect.map(cachedTokenFor(request), (cached) => GitHubClient.layerFromToken({
+	static cachedClientLayer = (request, options = {}) => Layer.unwrap(Effect.map(GitHubApp.cachedToken(request), (cached) => GitHubClient.layerFromToken({
 		...options,
 		token: cached.token.token
 	})));
 	/** An in-memory double; unstubbed members die naming themselves. */
-	static makeTest = (overrides = {}) => ({
-		token: overrides.token ?? (() => unstubbed("token")),
-		scopedToken: overrides.scopedToken ?? (() => unstubbed("scopedToken")),
-		revoke: overrides.revoke ?? (() => unstubbed("revoke")),
-		identity: overrides.identity ?? (() => unstubbed("identity")),
-		botUser: overrides.botUser ?? (() => unstubbed("botUser")),
-		installations: overrides.installations ?? (() => unstubbed("installations"))
-	});
+	static makeTest = (overrides = {}) => {
+		const token = overrides.token ?? (() => unstubbed("token"));
+		return {
+			token,
+			scopedToken: overrides.scopedToken ?? (() => unstubbed("scopedToken")),
+			revoke: overrides.revoke ?? (() => unstubbed("revoke")),
+			identity: overrides.identity ?? (() => unstubbed("identity")),
+			botUser: overrides.botUser ?? (() => unstubbed("botUser")),
+			installations: overrides.installations ?? (() => unstubbed("installations")),
+			cachedToken: overrides.cachedToken ?? makeCachedToken(token)
+		};
+	};
 	/** {@link GitHubApp.makeTest} behind a `Layer`. */
 	static layerTest = (overrides = {}) => Layer.succeed(GitHubApp, GitHubApp.makeTest(overrides));
 };
@@ -444,33 +457,64 @@ const DEFAULT_CACHE_MARGIN = Duration.minutes(5);
 const StoredToken = Schema.fromJsonString(InstallationToken);
 /** A store call that can never fail its caller: failures and defects become `fallback`; interruption propagates. */
 const swallowStore = (effect, fallback) => Effect.catchCause(effect, (cause) => Cause.hasInterruptsOnly(cause) ? Effect.failCause(cause) : Effect.succeed(fallback));
-const cachedTokenFor = Effect.fn("GitHubApp.cachedToken")(function* (request) {
-	const input = request.margin ?? DEFAULT_CACHE_MARGIN;
-	const margin = typeof input === "number" && !Number.isFinite(input) ? Option.none() : Option.filter(Duration.fromInput(input), (duration) => Duration.isFinite(duration) && !Duration.isNegative(duration));
-	if (Option.isNone(margin)) return yield* GitHubAppError.of("token", "the cache margin must be a finite, non-negative duration");
-	const app = yield* GitHubApp;
-	const store = yield* InstallationTokenStore;
-	const stored = yield* swallowStore(store.get(request.installationId), Option.none());
-	if (Option.isSome(stored)) {
-		const decoded = yield* Effect.option(Schema.decodeUnknownEffect(StoredToken)(stored.value));
-		const now = yield* Clock.currentTimeMillis;
-		if (Option.isSome(decoded) && decoded.value.installationId === request.installationId && !decoded.value.isExpired(now, margin.value)) return {
-			token: decoded.value,
-			source: "cached"
+/**
+* The caching read over `token`, with one in-flight mint per installation.
+*
+* @remarks
+* The map is the single-flight record. A key is present exactly while a mint
+* for that installation is running in this process; the first miss creates it
+* and forks the mint, later misses await the same `Deferred`, and the mint's
+* exit finalizer deletes the key before completing the `Deferred` with
+* whatever exit the mint produced, so a failed mint fails every waiter with the
+* same error and never pins the key. The mint is forked detached from the
+* leader, so the leader being interrupted does not interrupt the mint the
+* waiters depend on; the leader itself just stops waiting. The key is the
+* installation id alone because that is also the store's key: a `TokenRequest`
+* cannot narrow a token, so two requests for one installation ask for the same
+* token.
+*/
+const makeCachedToken = (token) => {
+	const inFlight = /* @__PURE__ */ new Map();
+	return Effect.fn("GitHubApp.cachedToken")(function* (request) {
+		const input = request.margin ?? DEFAULT_CACHE_MARGIN;
+		const margin = typeof input === "number" && !Number.isFinite(input) ? Option.none() : Option.filter(Duration.fromInput(input), (duration) => Duration.isFinite(duration) && !Duration.isNegative(duration));
+		if (Option.isNone(margin)) return yield* GitHubAppError.of("token", "the cache margin must be a finite, non-negative duration");
+		const store = yield* InstallationTokenStore;
+		const stored = yield* swallowStore(store.get(request.installationId), Option.none());
+		if (Option.isSome(stored)) {
+			const decoded = yield* Effect.option(Schema.decodeUnknownEffect(StoredToken)(stored.value));
+			const now = yield* Clock.currentTimeMillis;
+			if (Option.isSome(decoded) && decoded.value.installationId === request.installationId && !decoded.value.isExpired(now, margin.value)) return {
+				token: decoded.value,
+				source: "cached"
+			};
+		}
+		const joined = inFlight.get(request.installationId);
+		if (joined !== void 0) return {
+			token: yield* Deferred.await(joined),
+			source: "joined"
 		};
-	}
-	const minted = yield* app.token(request);
-	const now = yield* Clock.currentTimeMillis;
-	const ttlMillis = DateTime.toEpochMillis(minted.expiresAt) - Duration.toMillis(margin.value) - now;
-	if (ttlMillis > 0) {
-		const encoded = yield* Effect.option(Schema.encodeUnknownEffect(StoredToken)(minted));
-		if (Option.isSome(encoded)) yield* swallowStore(store.set(request.installationId, encoded.value, Duration.millis(ttlMillis)), void 0);
-	}
-	return {
-		token: minted,
-		source: "minted"
-	};
-});
+		const deferred = Deferred.makeUnsafe();
+		const mint = Effect.gen(function* () {
+			const minted = yield* token(request);
+			const now = yield* Clock.currentTimeMillis;
+			const ttlMillis = DateTime.toEpochMillis(minted.expiresAt) - Duration.toMillis(margin.value) - now;
+			if (ttlMillis > 0) {
+				const encoded = yield* Effect.option(Schema.encodeUnknownEffect(StoredToken)(minted));
+				if (Option.isSome(encoded)) yield* swallowStore(store.set(request.installationId, encoded.value, Duration.millis(ttlMillis)), void 0);
+			}
+			return minted;
+		}).pipe(Effect.onExit((exit) => Effect.andThen(Effect.sync(() => inFlight.delete(request.installationId)), Deferred.done(deferred, exit))));
+		yield* Effect.uninterruptible(Effect.suspend(() => {
+			inFlight.set(request.installationId, deferred);
+			return Effect.forkDetach(mint);
+		}));
+		return {
+			token: yield* Deferred.await(deferred),
+			source: "minted"
+		};
+	});
+};
 const unstubbed = (member) => {
 	throw new Error(`GitHubApp.makeTest: ${member}() was called but not stubbed — pass an override.`);
 };
@@ -566,7 +610,8 @@ function makeApp(options) {
 					login: user.login
 				} : raw).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(GitHubAppError.of("identity", "GitHub returned an unexpected bot user", error))));
 			}),
-			installations
+			installations,
+			cachedToken: makeCachedToken(token)
 		};
 	});
 }

package/index.d.ts

@@ -4,7 +4,6 @@ import { Cause, Config, Context, Duration, Effect, Layer, Option, Redacted, Resu
 import { PaginatingEndpoints } from "@octokit/plugin-paginate-rest";
 import { Endpoints, RequestHeaders } from "@octokit/types";
 import { SemVer } from "@effected/semver";
-//#endregion
 //#region src/ActionsOidc.d.ts
 declare const ActionsOidcClaims_base: Schema.Class<ActionsOidcClaims, Schema.Struct<{
   /** The issuer: always {@link ActionsOidc.issuer} once verified. */
@@ -600,9 +599,8 @@ export declare class RetryPolicy extends RetryPolicy_base {
    */
   schedule<E extends RetryableFailure>(): Schedule.Schedule<number, E>;
 }
-declare namespace Rest_d_exports {
-  export { Data, Item, PageOptions, PaginatingRoute, Params, RequestExtras, Response, Route };
-}
+//#endregion
+//#region src/Rest.d.ts
 /**
  * Every REST route GitHub documents, as a `"<METHOD> <path>"` literal — for
  * example `"GET /repos/{owner}/{repo}"`.
@@ -2474,8 +2472,17 @@ interface CachedTokenRequest extends TokenRequest {
 interface CachedToken {
   /** The token. */
   readonly token: InstallationToken;
-  /** `"cached"` when it was read from the store, `"minted"` when GitHub issued it just now. */
-  readonly source: "cached" | "minted";
+  /**
+   * `"cached"` when it was read from the store, `"minted"` when GitHub
+   * issued it to this call just now, `"joined"` when this call missed the
+   * store but another call in the same process was already minting for the
+   * installation and this one took that token instead of minting its own.
+   *
+   * @remarks
+   * A `"joined"` token is as fresh as a `"minted"` one; the label exists so
+   * a caller counting mints against GitHub can tell the two apart.
+   */
+  readonly source: "cached" | "minted" | "joined";
 }
 declare const InstallationToken_base: Schema.Class<InstallationToken, Schema.Struct<{
   /** The token. Decodes to `Redacted`, encodes back to the raw string. */
@@ -2803,9 +2810,18 @@ export declare class GitHubApp extends GitHubApp_base {
    * **A cached token is never revoked**: another scope or isolate may be using
    * it. It expires on its own, within the hour.
    *
-   * Two concurrent calls that both miss will both mint, and the later write
-   * wins. That is expected: the store may span isolates, so the kit cannot
-   * lock it, and an extra token costs one call and expires on its own.
+   * Within one process, concurrent misses for one installation are
+   * **single-flight**: the first caller mints and the others wait for that
+   * mint and return the same token with `source: "joined"`, so a batch that
+   * fans out over one installation on a cold store costs one mint, not one
+   * per fiber. The in-flight record lives with the `GitHubApp` service and is
+   * released when the mint settles, however it settles: a failed mint fails
+   * every waiter with the same `GitHubAppError`, and the next call mints
+   * again. Interrupting the leader does not strand the waiters: the mint runs
+   * in its own fiber and completes for them. Across isolates, two misses
+   * still both mint and the later write wins. That is expected: the store may
+   * span isolates, so the kit cannot lock it, and an extra token costs one
+   * call and expires on its own.
    *
    * The encoded value written to the store contains the raw token, so
    * encrypting it at rest is the store's job.
@@ -2912,6 +2928,19 @@ interface GitHubAppShape {
   readonly botUser: (request: BotUserRequest) => Effect.Effect<BotUser, GitHubAppError>;
   /** Every installation of the app. */
   readonly installations: (credentials: AppCredentials) => Effect.Effect<ReadonlyArray<Installation>, GitHubAppError>;
+  /**
+   * An installation token, reused from the {@link InstallationTokenStore}
+   * while it has `margin` left to live; {@link GitHubApp.cachedToken} is this
+   * member on the provided service.
+   *
+   * @remarks
+   * A member rather than a free function because the in-process
+   * single-flight record for concurrent misses lives with the service: it is
+   * created with the layer and shared by every call through it.
+   * {@link GitHubApp.makeTest} builds it over the double's `token`, so a test
+   * that stubs `token` gets the real caching and single-flight behaviour.
+   */
+  readonly cachedToken: (request: CachedTokenRequest) => Effect.Effect<CachedToken, GitHubAppError, InstallationTokenStore>;
 }
 //#endregion
 //#region src/GitHubCommit.d.ts

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/github",
-	"version": "0.18.0",
+	"version": "0.20.0",
 	"private": false,
 	"description": "Typed GitHub REST and GraphQL services over the octokit core request surface, with app auth and resource helpers.",
 	"keywords": [
@@ -38,9 +38,9 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effected/github-references": "^0.7.1",
-		"@effected/jwt": "^0.1.1",
-		"@effected/semver": "^0.11.1",
+		"@effected/github-references": "^0.9.0",
+		"@effected/jwt": "^0.3.0",
+		"@effected/semver": "^0.13.0",
 		"@octokit/core": "^7.0.6",
 		"@octokit/plugin-paginate-rest": "^16.0.0",
 		"@octokit/types": "^18.0.0",
@@ -48,7 +48,7 @@
 		"tweetnacl": "1.0.3"
 	},
 	"peerDependencies": {
-		"effect": "4.0.2"
+		"effect": "^4.0.0"
 	},
 	"engines": {
 		"node": ">=24.11.0"