anyclaw-sdk-service 0.2.1

use crate::error::ServiceSdkError;
use crate::types::{ServiceHealthStatus, ServiceInitializeParams, ServiceInitializeResult};

/// Trait for building service extensions.
///
/// Implement this trait to create a service binary that the supervisor manages
/// via JSON-RPC over stdio. The [`ServiceHarness`](crate::ServiceHarness)
/// handles all framing — implementors only need to provide the business logic.
pub trait Service: Send + 'static {
    /// Called when the supervisor sends the `initialize` request.
    ///
    /// The service should bind to a port (using `params.port` as a hint if
    /// provided) and return the actual port and any installation metadata.
    fn on_initialize(
        &mut self,
        params: ServiceInitializeParams,
    ) -> impl std::future::Future<Output = Result<ServiceInitializeResult, ServiceSdkError>> + Send;

    /// Called when the supervisor sends a `health` request.
    ///
    /// Return the current health status of the service.
    fn on_health(&self) -> impl std::future::Future<Output = ServiceHealthStatus> + Send;

    /// Called when the supervisor sends the `shutdown` request.
    ///
    /// The service should perform graceful cleanup (drain connections, flush
    /// state) and return. The harness exits after this method returns.
    fn on_shutdown(
        &mut self,
    ) -> impl std::future::Future<Output = Result<(), ServiceSdkError>> + Send;

    /// Handle an unrecognized JSON-RPC method.
    ///
    /// Return `Some(value)` to send a success response with that value.
    /// Return `None` (the default) to let the harness respond with a -32601 error.
    ///
    /// D-03 boundary: params and return type stay as `serde_json::Value` because unknown
    /// methods have no schema — the service cannot know the shape at compile time.
    fn handle_unknown(
        &mut self,
        _method: &str,
        // D-03: unknown method params have no fixed schema
        _params: serde_json::Value,
    ) -> Option<serde_json::Value> {
        None
    }
}