image_processor.proto

syntax = "proto3";

import "google/protobuf/any.proto";
import "google/protobuf/empty.proto";

// ImageProcessor provides image transformation operations.
service ImageProcessor {
    // Returns a list of supported transformations from the server, based on
    // filter_config.json.
    rpc GetTransformations(google.protobuf.Empty) returns (SupportedTransformations) {}

    // Transform applies the requested transformations to the image stream.
    rpc Transform(stream ImageMessage) returns (stream TransformedImageMessage) {}
}

// Parameter types for ParameterSpec.
enum ParamType {
    PARAM_STRING  = 0;  // free-form string value
    PARAM_INTEGER = 1;  // integer within [min_int, max_int]
    PARAM_ENUM    = 2;  // one of the values in allowed_values
    PARAM_DOUBLE  = 3;  // floating-point value within [min_double, max_double]
}

// Describes a single parameter accepted by a filter, including its type and constraints.
message ParameterSpec {
    string name                    = 1;  // parameter name, e.g. "direction", "degrees"
    ParamType type                 = 2;
    repeated string allowed_values = 3;  // for PARAM_ENUM: the valid values
    int32 min_int                  = 4;  // for PARAM_INTEGER: inclusive lower bound
    int32 max_int                  = 5;  // for PARAM_INTEGER: inclusive upper bound
    double min_double              = 6;  // for PARAM_DOUBLE: inclusive lower bound
    double max_double              = 7;  // for PARAM_DOUBLE: inclusive upper bound
}

// One filter/transformation from filter_config.json
message FilterConfig {
    string name = 1;                        // e.g. "rotate", "grayscale"
    string description = 2;                 // human-readable description
    repeated ParameterSpec parameters = 3;  // parameter specs, or empty for no-param filters
}

// List of available transformations (maps to filter_config.json "filters" array)
message SupportedTransformations {
    repeated FilterConfig filters = 1;
}

// One transformation step: the filter name and optional parameter values.
// name must match a filter name from FilterConfig (returned by GetTransformations).
// For filters that take parameters (e.g. rotate), set params, e.g. {"direction": "+", "degrees": "180"}.
message Transformation {
    string name = 1;                    // e.g. "rotate", "grayscale"
    map<string, string> params = 2;     // parameter name -> value; empty for no-parameter filters
}

// ImageMessage carries image bytes, image file type, and the ordered list of transformations to apply.
message ImageMessage {
    // Raw image bytes. Must not exceed 20 MB.
    // Width and height must each be between 10 px and 4096 px after decoding.
    bytes image_data = 1;

    // Input image file type. Must not be UNKNOWN.
    FileType image_format = 2;

    // Ordered list of transformations to apply. Must contain 1–10 items.
    // Each transformation name must match a value returned by GetTransformations.
    repeated Transformation transformations = 3;
}

// TransformedImageMessage returns the transformed image data, format, and optional thumbnail.
// Although right now there is not a filter that adjusts the file type, this could be implemented
// in the future.  Returning the image_format allows that.
message TransformedImageMessage {
    bytes image_data = 1;
    FileType image_format = 2; 
    // optional thumbnail bytes, could be empty
    repeated bytes thumbnail = 3;
}

// ErrorStatus carries gRPC error code, message, and optional details.
message ErrorStatus {
    // Status code: use values from [google.rpc.Code](https://github.com/googleapis/api-common-protos/blob/main/google/rpc/code.proto) (e.g. 3 = INVALID_ARGUMENT, 5 = NOT_FOUND).
    int32 code = 1;

    // A developer-facing error message.
    string message = 2;

    // A list of messages that carry the error details.
    repeated google.protobuf.Any details = 3;
}

// FileType indicates the supported image format for input and output.  Currently these are 
// chosen from [supported filetypes of the Pillow image processing library](https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html)  
enum FileType {
    UNKNOWN = 0;
    JPEG = 1;
    PNG = 2;
    WEBP = 3;
    GIF = 4;
    BMP = 5;
}