managing-apps/src/Managing.Application.Abstractions/Grains/ILiveBotRegistryGrain.cs

using Orleans;
using static Managing.Common.Enums;

namespace Managing.Application.Abstractions.Grains;

/// <summary>
/// Orleans grain interface for LiveBotRegistry operations.
/// This interface defines the distributed, async operations available for the bot registry.
/// The registry acts as a central, durable directory for all LiveTradingBot grains.
/// </summary>
public interface ILiveBotRegistryGrain : IGrainWithIntegerKey
{
    /// <summary>
    /// Registers a new bot with its user ID. This should be called by the LiveTradingBotGrain when it is first initialized.
    /// The initial status will be BotStatus.Up.
    /// </summary>
    /// <param name="identifier">The unique identifier of the bot</param>
    /// <param name="userId">The unique identifier of the user who owns the bot</param>
    /// <returns>A task that represents the asynchronous operation</returns>
    Task RegisterBot(Guid identifier, int userId);

    /// <summary>
    /// Removes a bot from the registry. This should be a full removal, perhaps called when a user permanently deletes a bot.
    /// </summary>
    /// <param name="identifier">The unique identifier of the bot to unregister</param>
    /// <returns>A task that represents the asynchronous operation</returns>
    Task UnregisterBot(Guid identifier);

    /// <summary>
    /// Returns a list of all bots in the registry. This is for a management dashboard to see all bots in the system.
    /// </summary>
    /// <returns>A list of all BotRegistryEntry objects in the registry</returns>
    Task<List<BotRegistryEntry>> GetAllBots();

    /// <summary>
    /// Returns a list of all bots associated with a specific user. This is the primary method for a user's watchlist.
    /// </summary>
    /// <param name="userId">The unique identifier of the user</param>
    /// <returns>A list of BotRegistryEntry objects for the specified user</returns>
    Task<List<BotRegistryEntry>> GetBotsForUser(int userId);

    /// <summary>
    /// A dedicated method for updating only the bot's Status field (Up/Down). 
    /// This will be called by LiveTradingBot's StartAsync and StopAsync methods.
    /// </summary>
    /// <param name="identifier">The unique identifier of the bot</param>
    /// <param name="status">The new status to set for the bot</param>
    /// <returns>A task that represents the asynchronous operation</returns>
    Task UpdateBotStatus(Guid identifier, BotStatus status);
    Task<BotStatus> GetBotStatus(Guid identifier);
}