token_source.h

/*
 * Copyright 2026 LiveKit
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the License governing permissions and limitations.
 */
 
#pragma once
 
#include <chrono>
#include <functional>
#include <future>
#include <map>
#include <memory>
#include <mutex>
#include <optional>
#include <string>
 
#include "livekit/result.h"
#include "livekit/visibility.h"
 
namespace livekit {
 
struct TokenSourceResponse {
  std::string server_url;
 
  std::string participant_token;
 
  std::optional<std::string> participant_name;
 
  std::optional<std::string> room_name;
};
 
struct TokenRequestOptions {
  std::optional<std::string> room_name;
 
  std::optional<std::string> participant_name;
 
  std::optional<std::string> participant_identity;
 
  std::optional<std::string> participant_metadata;
 
  std::map<std::string, std::string> participant_attributes;
 
  std::optional<std::string> agent_name;
 
  std::optional<std::string> agent_metadata;
 
  std::optional<std::string> agent_deployment;
};
 
struct TokenEndpointOptions {
  std::string method = "POST";
 
  std::map<std::string, std::string> headers;
 
  std::chrono::milliseconds timeout = std::chrono::seconds(30);
};
 
struct SandboxTokenServerOptions {
  std::string base_url = "https://cloud-api.livekit.io";
};
 
struct TokenSourceError {
  std::string message;
};
 
class LIVEKIT_API TokenSourceFixed {
public:
  virtual ~TokenSourceFixed() = default;
 
  virtual std::future<Result<TokenSourceResponse, TokenSourceError>> fetch() = 0;
};
 
class LIVEKIT_API TokenSourceConfigurable {
public:
  virtual ~TokenSourceConfigurable() = default;
 
  virtual std::future<Result<TokenSourceResponse, TokenSourceError>> fetch(const TokenRequestOptions& options = {}) = 0;
};
 
class LIVEKIT_API LiteralTokenSource final : public TokenSourceFixed {
public:
  static std::unique_ptr<LiteralTokenSource> create(std::string server_url, std::string participant_token);
 
  static std::unique_ptr<LiteralTokenSource> create(
      std::function<std::future<Result<TokenSourceResponse, TokenSourceError>>()> provider);
 
  std::future<Result<TokenSourceResponse, TokenSourceError>> fetch() override;
 
private:
  explicit LiteralTokenSource(TokenSourceResponse details);
  explicit LiteralTokenSource(std::function<std::future<Result<TokenSourceResponse, TokenSourceError>>()> provider);
 
  TokenSourceResponse details_;
  std::function<std::future<Result<TokenSourceResponse, TokenSourceError>>()> provider_;
};
 
class LIVEKIT_API CustomTokenSource final : public TokenSourceConfigurable {
public:
  static std::unique_ptr<CustomTokenSource> create(
      std::function<std::future<Result<TokenSourceResponse, TokenSourceError>>(const TokenRequestOptions&)> provider);
 
  std::future<Result<TokenSourceResponse, TokenSourceError>> fetch(const TokenRequestOptions& options = {}) override;
 
private:
  explicit CustomTokenSource(
      std::function<std::future<Result<TokenSourceResponse, TokenSourceError>>(const TokenRequestOptions&)> provider);
 
  std::function<std::future<Result<TokenSourceResponse, TokenSourceError>>(const TokenRequestOptions&)> provider_;
};
 
class LIVEKIT_API EndpointTokenSource final : public TokenSourceConfigurable {
public:
  static std::unique_ptr<EndpointTokenSource> create(std::string endpoint_url, TokenEndpointOptions options = {});
 
  std::future<Result<TokenSourceResponse, TokenSourceError>> fetch(const TokenRequestOptions& options = {}) override;
 
private:
  // Network transport seam. Mirrors the internal HTTP client signature
  // (returns the raw response body or an error string) so tests can inject a
  // stub and assert the serialized request / parse a canned response without a
  // live server. Defaults to the real HTTP client in production.
  using HttpTransport = std::function<Result<std::string, std::string>(
      const std::string& method, const std::string& url, const std::map<std::string, std::string>& headers,
      const std::string& json_body, std::chrono::milliseconds timeout)>;
 
  EndpointTokenSource(std::string endpoint_url, TokenEndpointOptions options, HttpTransport transport);
 
  Result<TokenSourceResponse, TokenSourceError> fetchSync(const TokenRequestOptions& options) const;
 
  std::string endpoint_url_;
  TokenEndpointOptions options_;
  HttpTransport transport_;
 
  friend struct EndpointTokenSourceTestAccess;
};
 
class LIVEKIT_API SandboxTokenSource final : public TokenSourceConfigurable {
public:
  static std::unique_ptr<SandboxTokenSource> create(const std::string& sandbox_id,
                                                    const SandboxTokenServerOptions& options = {});
 
  std::future<Result<TokenSourceResponse, TokenSourceError>> fetch(const TokenRequestOptions& options = {}) override;
 
private:
  explicit SandboxTokenSource(std::unique_ptr<TokenSourceConfigurable> endpoint);
 
  std::unique_ptr<TokenSourceConfigurable> endpoint_;
 
  friend struct SandboxTokenSourceTestAccess;
};
 
class LIVEKIT_API CachingTokenSource final : public TokenSourceConfigurable {
public:
  static std::unique_ptr<CachingTokenSource> create(std::unique_ptr<TokenSourceConfigurable> inner);
 
  std::future<Result<TokenSourceResponse, TokenSourceError>> fetch(const TokenRequestOptions& options = {}) override;
 
  void invalidate();
 
  std::optional<TokenSourceResponse> cachedResponse() const;
 
private:
  explicit CachingTokenSource(std::unique_ptr<TokenSourceConfigurable> inner);
 
  std::unique_ptr<TokenSourceConfigurable> inner_;
  mutable std::mutex mutex_;
  std::optional<TokenRequestOptions> cached_options_;
  std::optional<TokenSourceResponse> cached_details_;
};
 
} // namespace livekit