diff --git a/.changeset/goofy-rules-swim.md b/.changeset/goofy-rules-swim.md new file mode 100644 index 0000000000..b829fd5ca2 --- /dev/null +++ b/.changeset/goofy-rules-swim.md @@ -0,0 +1,5 @@ +--- +"livekit-client": minor +--- + +introduce DevelopmentTokenServer and deprecate SandboxTokenServer diff --git a/README.md b/README.md index 06b90f5151..86368086e7 100644 --- a/README.md +++ b/README.md @@ -336,7 +336,7 @@ room.connect(configurableResponse.serverUrl, configurableResponse.participantTok |Mechanism: | using pre-generated credentials | via a http request to a url | via fully custom logic | |-------------|--|--|--| |Fixed | [`TokenSource.literal`](#tokensourceliteral) | — | [`TokenSource.literal(async () => { /* ... */ })`](#tokensourceliteral) | -|Configurable | — | [`TokenSource.endpoint`](#tokensourceendpoint) or [`TokenSource.sandboxTokenServer`](#tokensourceendpoint) | [`TokenSource.custom`](#tokensourcecustom) | +|Configurable | — | [`TokenSource.endpoint`](#tokensourceendpoint) or [`TokenSource.developmentTokenServer`](#tokensourcedevelopmenttokenserver) | [`TokenSource.custom`](#tokensourcecustom) | #### TokenSource.Literal A fixed token source which returns a static set of credentials or a computed set of credentials @@ -373,21 +373,22 @@ const endpoint2 = TokenSource.endpoint("http://example.com/credentials-endpoint" await endpoint2.fetch({ agentName: "agent to dispatch" }) // { serverUrl: "...", participantToken: "... token encoding agentName ..." } ``` -#### TokenSource.SandboxTokenServer +#### TokenSource.DevelopmentTokenServer A configurable token source which makes a request to a -[sandbox token server endpoint](https://cloud.livekit.io/projects/p_/sandbox/templates/token-server), +// TODO fix the dashboard link +[development token server endpoint](https://cloud.livekit.io/projects/p_/sandbox/templates/token-server), a LiveKit-hosted token generation mechanism. This token generation mechanism is inherently insecure and should only be used for prototyping; do NOT use in production. -One parameter is required - the sandbox id from the dashboard. This is the `token-server-xxxxxx` +One parameter is required - the development token server id from the dashboard. This is the `token-server-xxxxxx` value in `https://token-server-xxxxxx.sandbox.livekit.io`. Example: ```ts -const sandbox = TokenSource.sandboxTokenServer("token-server-xxxxxx"); -await sandbox.fetch({ agentName: "agent to dispatch" }); // { serverUrl: "...", participantToken: "... token encoding agentName ..." } +const devTokenSource = TokenSource.developmentTokenServer("token-server-xxxxxx"); +await devTokenSource.fetch({ agentName: "agent to dispatch" }); // { serverUrl: "...", participantToken: "... token encoding agentName ..." } ``` #### TokenSource.Custom @@ -401,11 +402,11 @@ output token. If you'd rather implement a fixed version of this TokenSource, see Example: ```ts -const sandbox = TokenSource.custom(async (options) => { +const myTokenSource = TokenSource.custom(async (options) => { // generate token info via custom means here return { serverUrl: "...", participantToken: "... options encoded in here ..." }; }); -await sandbox.fetch({ agentName: "agent to dispatch" }); +await myTokenSource.fetch({ agentName: "agent to dispatch" }); ``` ### RPC diff --git a/src/room/token-source/TokenSource.ts b/src/room/token-source/TokenSource.ts index 071aac5faa..305ed687c4 100644 --- a/src/room/token-source/TokenSource.ts +++ b/src/room/token-source/TokenSource.ts @@ -213,29 +213,35 @@ class TokenSourceEndpoint extends TokenSourceCached { const body = await response.json(); return TokenSourceResponse.fromJson(body, { // NOTE: it could be possible that the response body could contain more fields than just - // what's in TokenSourceResponse depending on the implementation (ie, SandboxTokenServer) + // what's in TokenSourceResponse depending on the implementation (ie, DevelopmentTokenServer) ignoreUnknownFields: true, }); } } -export type SandboxTokenServerOptions = { +export type DevelopmentTokenServerOptions = { baseUrl?: string; }; - -class TokenSourceSandboxTokenServer extends TokenSourceEndpoint { - constructor(sandboxId: string, options: SandboxTokenServerOptions) { +class TokenSourceDevelopmentTokenServer extends TokenSourceEndpoint { + constructor(tokenServerId: string, options: DevelopmentTokenServerOptions) { const { baseUrl = 'https://cloud-api.livekit.io', ...rest } = options; + // TODO is there an alternative path (and header) already that we could use instead of the sandbox naming one? super(`${baseUrl}/api/v2/sandbox/connection-details`, { ...rest, headers: { - 'X-Sandbox-ID': sandboxId, + 'X-Sandbox-ID': tokenServerId, }, }); } } +/** @deprecated use {@link DevelopmentTokenServerOptions} instead */ +export type SandboxTokenServerOptions = DevelopmentTokenServerOptions; + +/** @deprecated Use {@link TokenSourceDevelopmentTokenServer} instead */ +class TokenSourceSandboxTokenServer extends TokenSourceDevelopmentTokenServer {} + export { /** The return type of {@link TokenSource.literal} */ type TokenSourceLiteral, @@ -243,8 +249,9 @@ export { type TokenSourceCustom, /** The return type of {@link TokenSource.endpoint} */ type TokenSourceEndpoint, - /** The return type of {@link TokenSource.sandboxTokenServer} */ type TokenSourceSandboxTokenServer, + /** The return type of {@link TokenSource.developmentTokenServer} */ + type TokenSourceDevelopmentTokenServer, decodeTokenPayload, areTokenSourceFetchOptionsEqual, }; @@ -276,7 +283,14 @@ export const TokenSource = { }, /** - * TokenSource.sandboxTokenServer queries a sandbox token server for credentials, + * @deprecated Use {@link TokenSource.developmentTokenServer} instead + */ + sandboxTokenServer(sandboxId: string, options: SandboxTokenServerOptions = {}) { + return new TokenSourceSandboxTokenServer(sandboxId, options); + }, + + /** + * TokenSource.developmentTokenServer queries a development token server for credentials, * which supports quick prototyping / getting started types of use cases. * * This token provider is INSECURE and should NOT be used in production. @@ -284,7 +298,7 @@ export const TokenSource = { * For more info: * @see https://cloud.livekit.io/projects/p_/sandbox/templates/token-server */ - sandboxTokenServer(sandboxId: string, options: SandboxTokenServerOptions = {}) { - return new TokenSourceSandboxTokenServer(sandboxId, options); + developmentTokenServer(tokenServerId: string, options: DevelopmentTokenServerOptions = {}) { + return new TokenSourceDevelopmentTokenServer(tokenServerId, options); }, };