// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
 
using System;
using System.Collections.Generic;
using System.Diagnostics.CodeAnalysis;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Shared.DiagnosticIds;
 
namespace Microsoft.Extensions.AI;
 
/// <summary>Represents a real-time session.</summary>
/// <remarks>This interface provides methods to manage a real-time session and to interact with the real-time model.</remarks>
[Experimental(DiagnosticIds.Experiments.AIRealTime, UrlFormat = DiagnosticIds.UrlFormat)]
public interface IRealtimeClientSession : IAsyncDisposable
{
    /// <summary>
    /// Gets the current session options.
    /// </summary>
    RealtimeSessionOptions? Options { get; }
 
    /// <summary>
    /// Sends a client message to the session.
    /// </summary>
    /// <param name="message">The client message to send.</param>
    /// <param name="cancellationToken">A token to cancel the operation.</param>
    /// <returns>A task that represents the asynchronous send operation.</returns>
    /// <remarks>
    /// <para>
    /// This method allows for sending client messages to the session at any time, which can be used to influence the session's behavior or state.
    /// </para>
    /// <para>
    /// <strong>Concurrency note for provider implementers:</strong> <see cref="SendAsync"/> may be called concurrently
    /// from multiple sources. For example, a caller may stream audio via <see cref="SendAsync"/> on one thread while
    /// middleware such as <c>FunctionInvokingRealtimeClientSession</c> calls <see cref="SendAsync"/> to return tool results
    /// from within <see cref="GetStreamingResponseAsync"/> enumeration on another thread. If the underlying transport
    /// (e.g., a WebSocket) does not support concurrent sends, provider implementations must serialize access — for
    /// example by using a <see cref="System.Threading.SemaphoreSlim"/> — to prevent protocol violations.
    /// </para>
    /// </remarks>
    Task SendAsync(RealtimeClientMessage message, CancellationToken cancellationToken = default);
 
    /// <summary>Streams the response from the real-time session.</summary>
    /// <param name="cancellationToken">A token to cancel the operation.</param>
    /// <returns>The response messages generated by the session.</returns>
    /// <remarks>
    /// This method cannot be called multiple times concurrently on the same session instance.
    /// </remarks>
    IAsyncEnumerable<RealtimeServerMessage> GetStreamingResponseAsync(
            CancellationToken cancellationToken = default);
 
    /// <summary>Asks the <see cref="IRealtimeClientSession"/> for an object of the specified type <paramref name="serviceType"/>.</summary>
    /// <param name="serviceType">The type of object being requested.</param>
    /// <param name="serviceKey">An optional key that can be used to help identify the target service.</param>
    /// <returns>The found object, otherwise <see langword="null"/>.</returns>
    /// <exception cref="ArgumentNullException"><paramref name="serviceType"/> is <see langword="null"/>.</exception>
    /// <remarks>
    /// The purpose of this method is to allow for the retrieval of strongly typed services that might be provided by the <see cref="IRealtimeClientSession"/>,
    /// including itself or any services it might be wrapping.
    /// </remarks>
    object? GetService(Type serviceType, object? serviceKey = null);
}