plugin sdk request manager

About plugin request handling

Plugins can handle custom requests from client applications (custom tasks, config pages, other plugins) using the RequestManager.

Request/Response Architecture

sequenceDiagram
    participant Client as Client application
    participant ClientRM as SDK RequestManager (client)
    participant Directory
    participant PluginRM as SDK RequestManager (plugin)
    participant Handler as Request handler

    Client->>ClientRM: SendRequest TRequest to TResponse
    ClientRM->>ClientRM: Resolve recipient to role owner
    ClientRM->>Directory: Send request
    Directory->>PluginRM: Dispatch request to role
    PluginRM->>Handler: Invoke registered handler
    Handler-->>PluginRM: RequestCompletion TResponse
    PluginRM-->>Directory: Send response
    Directory-->>ClientRM: Return response
    ClientRM-->>Client: TResponse

Loading

Key concepts:

• Request/response communication pattern (RPC-style)
• Type-safe request and response classes
• Requests target a recipient entity GUID
• Multiple handlers for different request types
• Synchronous, asynchronous, and completion-based handlers

Use Cases

Custom configuration pages:

• Page requests current settings
• Plugin returns configuration
• Page sends updated settings
• Plugin validates and applies

Custom tasks:

• User triggers task in Security Desk
• Task sends command to plugin
• Plugin executes operation
• Returns result to task

Inter-plugin communication:

• One plugin requests data from another
• Plugins coordinate actions
• Share state or resources

Diagnostics and testing:

• Test connections
• Query internal state
• Trigger operations
• Get statistics

Request Handler Types

Synchronous Handler

Simple function that returns response immediately:

protected override void OnPluginLoaded()
{
    // Use Plugin's protected helper method
    AddRequestHandler<GetStatusRequest, StatusResponse>(HandleGetStatus);
}

private StatusResponse HandleGetStatus(GetStatusRequest request)
{
    return new StatusResponse
    {
        IsConnected = m_isConnected,
        DeviceCount = m_devices.Count,
        Uptime = DateTime.UtcNow - m_startTime
    };
}

When to use:

• Fast operations (< 100ms)
• No I/O required
• Simple data retrieval
• Immediate results available

Asynchronous Handler (Task-based)

Async method that can await operations:

protected override void OnPluginLoaded()
{
    // Use Plugin's protected helper method
    AddAsyncRequestHandler<TestConnectionRequest, TestConnectionResponse>(
        HandleTestConnectionAsync);
}

private async Task<TestConnectionResponse> HandleTestConnectionAsync(
    TestConnectionRequest request,
    RequestManagerContext context)
{
    try
    {
        var startTime = DateTime.UtcNow;
        await TestConnectionToExternalSystemAsync(
            request.Timeout,
            context.RequestCancellationToken);
        var elapsed = DateTime.UtcNow - startTime;
        
        return new TestConnectionResponse
        {
            Success = true,
            ResponseTime = elapsed
        };
    }
    catch (Exception ex)
    {
        return new TestConnectionResponse
        {
            Success = false,
            Error = ex.Message
        };
    }
}

When to use:

• Slow operations (> 100ms)
• I/O operations (database, network)
• Long-running tasks
• Need async/await
• Need cancellation support or user context

RequestManagerContext

The RequestManagerContext parameter provides information about the request origin and supports cancellation:

Properties

public class RequestManagerContext
{
    // Cancellation support
    CancellationToken RequestCancellationToken { get; }
    TimeSpan RequestTimeout { get; }
    
    // Request source information
    Guid SourceApplication { get; }     // Application that sent request
    Guid SourceUser { get; }            // User who initiated request
    string SourceUsername { get; }      // Username of requester
    
    // Request metadata
    DateTime ReceptionTimestamp { get; }              // When request was received (UTC)
    IReadOnlyCollection<Guid> DestinationEntities { get; } // Target entities
}

Usage Examples

Cancellation support:

private async Task<Response> HandleRequestAsync(
    Request request,
    RequestManagerContext context)
{
    // Pass cancellation token to async operations
    var data = await FetchDataAsync(context.RequestCancellationToken);
    
    // Check if cancelled
    if (context.RequestCancellationToken.IsCancellationRequested)
        return new Response { Cancelled = true };
        
    return new Response { Data = data };
}

User-specific logic:

private Response HandleRequest(Request request, RequestManagerContext context)
{
    var user = Engine.GetEntity<User>(context.SourceUser);
    
    Logger.TraceInformation($"Request from {context.SourceUsername} received at {context.ReceptionTimestamp}");
    
    // Apply user-specific permissions or behavior
    if (user.HasPrivilege(MyPrivilege))
    {
        return ProcessRequest(request);
    }
    
    return new Response { Error = "Insufficient privileges" };
}

Timeout handling:

private async Task<Response> HandleRequestAsync(
    Request request,
    RequestManagerContext context)
{
    Logger.TraceDebug($"Request timeout: {context.RequestTimeout}");
    
    try
    {
        // Use the timeout from context
        using var cts = CancellationTokenSource.CreateLinkedTokenSource(
            context.RequestCancellationToken);
        cts.CancelAfter(context.RequestTimeout);
        
        return await ProcessWithTimeoutAsync(request, cts.Token);
    }
    catch (OperationCanceledException)
    {
        return new Response { Error = "Request timed out" };
    }
}

Completion-based Handler

Callback pattern for complex scenarios:

protected override void OnPluginLoaded()
{
    // Use Plugin's protected helper method
    AddRequestHandler<ComplexRequest, ComplexResponse>(HandleComplexRequest);
}

private void HandleComplexRequest(
    ComplexRequest request,
    RequestCompletion<ComplexResponse> completion)
{
    // Process in background
    Task.Run(async () =>
    {
        try
        {
            var result = await ProcessComplexOperationAsync(request);
            completion.SetResponse(new ComplexResponse { Result = result });
        }
        catch (Exception ex)
        {
            completion.SetError(ex);
        }
    });
}

When to use:

• Need manual control over completion
• Complex error handling
• Progress reporting scenarios
• Legacy async patterns

Registering Handlers

Register in OnPluginLoaded

protected override void OnPluginLoaded()
{
    // Register multiple handlers using Plugin's protected helper methods
    AddRequestHandler<GetConfigRequest, PluginConfig>(HandleGetConfig);
    AddRequestHandler<SetConfigRequest, SetConfigResponse>(HandleSetConfig);
    AddAsyncRequestHandler<TestConnectionRequest, TestConnectionResponse>(
        HandleTestConnectionAsync);
}

Remove in Dispose

protected override void Dispose(bool disposing)
{
    if (disposing)
    {
        // Remove handlers using Plugin's protected helper methods
        RemoveRequestHandler<GetConfigRequest, PluginConfig>(HandleGetConfig);
        RemoveRequestHandler<SetConfigRequest, SetConfigResponse>(HandleSetConfig);
        RemoveAsyncRequestHandler<TestConnectionRequest, TestConnectionResponse>(
            HandleTestConnectionAsync);
    }
}

Important

• Register handlers in OnPluginLoaded()
• Remove handlers in Dispose()
• Match handler type when removing (sync vs async)

Request Routing

How Routing Works

Requests are routed by:

1. Request type - The generic type TRequest
2. Recipient entity - The GUID passed to SendRequest
3. Handler registration - Plugin must register handler for type

If the recipient entity is owned by a plugin role, the RequestManager routes the request to the owner role. Multiple plugins can handle the same request type as long as the recipient entity differs.

Request Classes

Define request and response classes:

[Serializable]
public class GetDeviceListRequest
{
    public bool IncludeOffline { get; set; }
    public DateTime Since { get; set; }
}

[Serializable]
public class DeviceListResponse
{
    public List<DeviceInfo> Devices { get; set; }
    public int TotalCount { get; set; }
}

[Serializable]
public class DeviceInfo
{
    public Guid DeviceGuid { get; set; }
    public string Name { get; set; }
    public bool IsOnline { get; set; }
}

Requirements:

• Must be [Serializable]
• Must be able to serialize/deserialize (JSON or binary)
• Keep classes simple (POCOs)
• Avoid complex object graphs

Common Request Patterns

Configuration Requests

// Get configuration
AddRequestHandler<GetConfigRequest, PluginConfig>(request => LoadConfiguration());

// Set configuration
AddRequestHandler<SetConfigRequest, SetConfigResponse>(request =>
{
    try
    {
        if (!ValidateConfiguration(request.Config, out string error))
        {
            return new SetConfigResponse
            {
                Success = false,
                Error = error
            };
        }

        UpdateConfiguration(request.Config);
        ApplyConfiguration(request.Config);

        return new SetConfigResponse { Success = true };
    }
    catch (Exception ex)
    {
        Logger.TraceError(ex, "Failed to update configuration");
        return new SetConfigResponse
        {
            Success = false,
            Error = ex.Message
        };
    }
});

Test Connection

AddAsyncRequestHandler<TestConnectionRequest, TestConnectionResponse>(
    async (request, context) =>
    {
        var sw = Stopwatch.StartNew();

        try
        {
            await ConnectToExternalSystemAsync(
                request.Timeout,
                context.RequestCancellationToken);

            return new TestConnectionResponse
            {
                Success = true,
                Message = "Connection successful",
                ResponseTime = sw.Elapsed
            };
        }
        catch (TimeoutException)
        {
            return new TestConnectionResponse
            {
                Success = false,
                Message = "Connection timeout",
                ResponseTime = sw.Elapsed
            };
        }
        catch (Exception ex)
        {
            return new TestConnectionResponse
            {
                Success = false,
                Message = ex.Message,
                ResponseTime = sw.Elapsed
            };
        }
    });

Execute Command

AddAsyncRequestHandler<ExecuteCommandRequest, CommandResponse>(
    async (request, context) =>
    {
        try
        {
            var result = await ExecuteCommandOnHardwareAsync(
                request.DeviceGuid,
                request.Command,
                request.Parameters,
                context.RequestCancellationToken);

            return new CommandResponse
            {
                Success = true,
                Result = result
            };
        }
        catch (Exception ex)
        {
            Logger.TraceError(ex, "Command execution failed");
            return new CommandResponse
            {
                Success = false,
                Error = ex.Message
            };
        }
    });

Query State

AddRequestHandler<GetDeviceStateRequest, DeviceStateResponse>(request =>
{
    var device = m_devices.FirstOrDefault(d => d.Guid == request.DeviceGuid);

    if (device == null)
    {
        return new DeviceStateResponse { Found = false };
    }

    return new DeviceStateResponse
    {
        Found = true,
        State = device.State,
        LastUpdate = device.LastUpdate,
        Properties = device.GetProperties()
    };
});

Error Handling

Return Error in Response

private SetConfigResponse HandleSetConfig(SetConfigRequest request)
{
    try
    {
        ValidateAndApplyConfig(request.Config);
        return new SetConfigResponse { Success = true };
    }
    catch (ValidationException ex)
    {
        return new SetConfigResponse 
        { 
            Success = false, 
            Error = ex.Message,
            ValidationErrors = ex.Errors
        };
    }
    catch (Exception ex)
    {
        Logger.TraceError(ex, "Configuration update failed");
        return new SetConfigResponse 
        { 
            Success = false, 
            Error = "Internal error occurred"
        };
    }
}

Throw Exception

private StatusResponse HandleGetStatus(GetStatusRequest request)
{
    if (!m_initialized)
    {
        throw new InvalidOperationException("Plugin not initialized");
    }
    
    return new StatusResponse { ... };
}

Exception handling:

• Exceptions are serialized and sent to client
• Client receives exception details
• Use exceptions for unexpected errors
• Prefer returning error in response for expected errors

Thread Safety

Request handlers run on a background thread, not the engine thread. Use Engine.QueueUpdate() or Engine.QueueUpdateAndWait() when work needs to update entities or other Engine state.

If handler spawns async work:

private void HandleLongOperation(
    LongOperationRequest request,
    RequestCompletion<LongOperationResponse> completion)
{
    Task.Run(async () =>
    {
        var result = await DoLongWorkAsync();

        // Queue back to engine thread for Engine access
        Engine.QueueUpdate(() =>
        {
            UpdateEntityState(result);
            completion.SetResponse(new LongOperationResponse { ... });
        });
    });
}

Federated Action Requests

Plugins can receive requests that cross Security Center federation boundaries using OnSdkFederationActionRequestReceived().

Overview

Federated action requests allow communication between plugins across federated Security Center systems. The request and response use serialized string payloads, giving you flexibility in the data format.

protected virtual SdkFederationActionResponse OnSdkFederationActionRequestReceived(
    SdkFederationActionRequest request)

Returns: null by default. Override to handle requests.

SdkFederationActionRequest

Property	Type	Description
Request	string	Serialized request payload
RequestId	Guid	Unique identifier for this request

SdkFederationActionResponse

Property	Type	Description
Response	string	Serialized response payload

Implementation Example

[Serializable]
public class MyFederatedRequest
{
    public string Command { get; set; }
    public Dictionary<string, string> Parameters { get; set; }
}

[Serializable]
public class MyFederatedResponse
{
    public bool Success { get; set; }
    public string Result { get; set; }
    public string Error { get; set; }
}

public class MyPlugin : Plugin
{
    protected override SdkFederationActionResponse OnSdkFederationActionRequestReceived(
        SdkFederationActionRequest request)
    {
        try
        {
            // Deserialize the request
            var federatedRequest = JsonConvert.DeserializeObject<MyFederatedRequest>(
                request.Request);

            Logger.TraceInformation(
                $"Received federated request {request.RequestId}: {federatedRequest.Command}");

            // Process the request
            string result = ProcessCommand(federatedRequest.Command, federatedRequest.Parameters);

            // Create and serialize response
            var response = new MyFederatedResponse
            {
                Success = true,
                Result = result
            };

            return new SdkFederationActionResponse(JsonConvert.SerializeObject(response));
        }
        catch (Exception ex)
        {
            Logger.TraceError(ex, "Failed to process federated request");

            var errorResponse = new MyFederatedResponse
            {
                Success = false,
                Error = ex.Message
            };

            return new SdkFederationActionResponse(JsonConvert.SerializeObject(errorResponse));
        }
    }

    private string ProcessCommand(string command, Dictionary<string, string> parameters)
    {
        // Implement command processing logic
        return $"Processed: {command}";
    }
}

Usage notes:

• Use JSON or another serialization format for request/response payloads
• Return null if your plugin does not handle federated requests
• Handle exceptions and return error responses rather than throwing
• Works for both federated and non-federated Security Center deployments

Related Guides

• Plugin SDK Overview - Plugin architecture
• Plugin SDK Threading - Threading for async request handlers
• Plugin SDK Lifecycle - When to register handlers
• Plugin SDK Configuration - Configuration request pattern
• Logging - Request logging