pkg/bufman/proto/registry/v1alpha1/plugin_curation.proto

syntax = "proto3";

package bufman.dubbo.apache.org.registry.v1alpha1;

import "image/v1/image.proto";
import "google/protobuf/compiler/plugin.proto";
import "google/protobuf/timestamp.proto";

// CuratedPluginVisibility defines the visibility options available
// for Curated Plugins.
enum CuratedPluginVisibility {
  CURATED_PLUGIN_VISIBILITY_UNSPECIFIED = 0;
  CURATED_PLUGIN_VISIBILITY_PUBLIC = 1;
  CURATED_PLUGIN_VISIBILITY_PRIVATE = 2;
}

// The supported plugin registries for curated plugins.
enum PluginRegistryType {
  PLUGIN_REGISTRY_TYPE_UNSPECIFIED = 0;
  PLUGIN_REGISTRY_TYPE_GO = 1;
  PLUGIN_REGISTRY_TYPE_NPM = 2;
  PLUGIN_REGISTRY_TYPE_MAVEN = 3;
  PLUGIN_REGISTRY_TYPE_SWIFT = 4;
}

// PluginLanguage is used to specify the output languages a plugin supports.
enum PluginLanguage {
  PLUGIN_LANGUAGE_UNSPECIFIED = 0;
  PLUGIN_LANGUAGE_GO = 1;
  PLUGIN_LANGUAGE_JAVASCRIPT = 2;
  PLUGIN_LANGUAGE_TYPESCRIPT = 3;
  PLUGIN_LANGUAGE_SWIFT = 4;
  PLUGIN_LANGUAGE_CPP = 5;
  PLUGIN_LANGUAGE_JAVA = 6;
  PLUGIN_LANGUAGE_DART = 7;
  PLUGIN_LANGUAGE_RUST = 8;
  PLUGIN_LANGUAGE_PYTHON = 9;
  PLUGIN_LANGUAGE_RUBY = 10;
  PLUGIN_LANGUAGE_KOTLIN = 11;
  PLUGIN_LANGUAGE_OBJECTIVE_C = 12;
  PLUGIN_LANGUAGE_PHP = 13;
  PLUGIN_LANGUAGE_CSHARP = 14;
  PLUGIN_LANGUAGE_SCALA = 15;
}

// NPMImportStyle is used to specify the import style the plugin supports.
enum NPMImportStyle {
  NPM_IMPORT_STYLE_UNSPECIFIED = 0;
  NPM_IMPORT_STYLE_MODULE = 1;
  NPM_IMPORT_STYLE_COMMONJS = 2;
}

// SwiftPlatformType is used to specify the platform type for a Swift plugins minimum compatible version.
enum SwiftPlatformType {
  SWIFT_PLATFORM_TYPE_UNSPECIFIED = 0;
  SWIFT_PLATFORM_TYPE_MACOS = 1;
  SWIFT_PLATFORM_TYPE_IOS = 2;
  SWIFT_PLATFORM_TYPE_WATCHOS = 3;
  SWIFT_PLATFORM_TYPE_TVOS = 4;
}

// GoConfig is the configuration for a Go plugin.
message GoConfig {
  // RuntimeLibrary describes the runtime library dependency of the generated code.
  message RuntimeLibrary {
    // The name of the runtime library module, i.e. "google.golang.org/protobuf".
    string module = 1;
    // The version of the runtime library, i.e. "v1.27.1".
    string version = 2;
  }
  // Optionally define the runtime libraries for the plugin.
  repeated RuntimeLibrary runtime_libraries = 1;
  // The minimum Go version required by the plugin.
  string minimum_version = 2;
}

// NPMConfig is the configuration for a JavaScript NPM plugin.
message NPMConfig {
  // RuntimeLibrary describes the runtime library dependency of the generated code.
  message RuntimeLibrary {
    // The name of the runtime library package, i.e. "@grpc/grpc-js".
    string package = 1;
    // The version of the runtime library, i.e. "^1.27.1".
    string version = 2;
  }
  // Optionally define the runtime libraries for the plugin.
  repeated RuntimeLibrary runtime_libraries = 1;
  // Optionally define a configuration for rewriting import paths, a feature mainly
  // used for remote code generation in the BSR npm registry, which makes it possible
  // to serve the output of a BSR module and a plugin in an individual package.
  //
  // All plugins based on @bufbuild/protoplugin support the option "rewrite_imports".
  // Setting this value, i.e. "connectweb.js" or "pb.js", informs the BSR npm registry
  // that the plugin supports import rewrites with the given import suffix.
  string rewrite_import_path_suffix = 2;
  // The import style used for the "type" field in the package.json file.
  // This exists to support legacy plugins that require "commonjs" support.
  NPMImportStyle import_style = 3;
}

// MavenConfig is the configuration for a Maven plugin.
message MavenConfig {
  // RuntimeLibrary describes a runtime dependency of the generated code.
  message RuntimeLibrary {
    string group_id = 1;
    string artifact_id = 2;
    string version = 3;
    string classifier = 4;
    string extension = 5;
  }
  // CompilerConfig contains configuration for the Java and/or Kotlin compiler used when compiling the generated code.
  message CompilerConfig {
    CompilerJavaConfig java = 1;
    CompilerKotlinConfig kotlin = 2;
  }
  // CompilerJavaConfig contains settings for the Java compiler.
  message CompilerJavaConfig {
    // File encoding (default: UTF-8).
    string encoding = 1;
    // Release version (default: 8).
    int32 release = 2;
    // Source version (default: 8).
    int32 source = 3;
    // Target version (default: 8).
    int32 target = 4;
  }
  // CompilerKotlinConfig contains settings for the Kotlin compiler.
  message CompilerKotlinConfig {
    // Version of the Kotlin compiler used to compile the generated code.
    string version = 1;
    // Version of the Kotlin API to target.
    string api_version = 2;
    // Target version of the JVM bytecode (default: 1.8).
    string jvm_target = 3;
    // Kotlin language version used for source compatibility.
    string language_version = 4;
  }
  // RuntimeConfig allows configuring additional runtimes (like the 'lite' runtime).
  // They can use different runtime dependencies and plugin options.
  message RuntimeConfig {
    string name = 1;
    repeated RuntimeLibrary runtime_libraries = 2;
    // The options to pass to the plugin. These will
    // be merged into a single, comma-separated string.
    repeated string options = 3;
  }

  // Optionally define the runtime libraries for the plugin.
  repeated RuntimeLibrary runtime_libraries = 1;
  // Settings for the Java/Kotlin compiler used to compile the generated code.
  CompilerConfig compiler = 2;
  // Optional additional runtimes supported by the plugin.
  repeated RuntimeConfig additional_runtimes = 3;
}

message SwiftConfig {
  // RuntimeLibrary describes a runtime library dependency of the generated code.
  message RuntimeLibrary {
    // The source of the runtime library package, e.g. https://github.com/apple/swift-protobuf.git.
    string source = 1;
    // The name of the runtime library package, e.g. "swift-protobuf".
    string package = 2;
    // The version of the runtime library, e.g. "1.21.0".
    string version = 3;
    // The products exported by the runtime library, e.g. "SwiftProtobuf".
    repeated string products = 4;
    // The minimum compatible platform versions of the runtime library.
    message Platform {
      // The name of the platform.
      SwiftPlatformType name = 1;
      // The minimum compatible version of the platform.
      string version = 2;
    }
    // The minimum compatible platform versions of the runtime library.
    repeated Platform platforms = 5;
    // The supported Swift language versions of the runtime library, e.g. ".v5".
    repeated string swift_versions = 6;
  }
  // Optionally define the runtime libraries for the plugin.
  repeated RuntimeLibrary runtime_libraries = 1;
}

// RegistryConfig is the configuration for the remote registry of a plugin.
message RegistryConfig {
  oneof registry_config {
    GoConfig go_config = 1;
    NPMConfig npm_config = 2;
    MavenConfig maven_config = 3;
    SwiftConfig swift_config = 4;
  }
  // Reserved for future remote registry types.
  reserved 5 to 9;
  // The options to pass to the plugin. These will
  // be merged into a single, comma-separated string.
  repeated string options = 10;
}

message CuratedPluginReference {
  // The owner of the plugin, i.e. "library".
  string owner = 1;
  // The name of the plugin, i.e. "connect-go".
  string name = 2;
  // Semver-formatted plugin version.
  string version = 3;
  // The revision for this plugin version.
  uint32 revision = 4;
}

// CuratedPlugin represents a protoc plugin curated by Buf, such as protoc-gen-go.
message CuratedPlugin {
  // The ID of the plugin, which uniquely identifies the plugin.
  string id = 1;
  // The owner of the plugin, i.e. "library".
  string owner = 2;
  // The name of the plugin, i.e. "connect-go".
  string name = 3;
  // The optional registry type of the plugin.
  PluginRegistryType registry_type = 4;
  // Semver-formatted plugin version.
  string version = 5;
  // The full container image digest associated with this plugin version including
  // the algorithm.
  // Ref: https://github.com/opencontainers/image-spec/blob/main/descriptor.md#digests
  string container_image_digest = 6;
  // The creation time of the plugin.
  google.protobuf.Timestamp create_time = 8;
  // List of plugin dependencies.
  repeated CuratedPluginReference dependencies = 9;
  // Optionally specify the URL leading to the source code of the plugin, if available.
  string source_url = 10;
  // Optionally specify a brief description of the plugin functionality.
  string description = 11;
  // The configuration for the remote registry of the plugin.
  RegistryConfig registry_config = 12;
  // The revision for this plugin version.
  uint32 revision = 13;
  // The output languages supported by the plugin.
  repeated PluginLanguage output_languages = 14;
  // spdx_license_id is the license of the plugin, which should be one of the identifiers
  // defined in https://spdx.org/licenses
  string spdx_license_id = 15;
  // license_url specifies an optional URL for the plugin's license (if not using a standard spdx_license_id).
  string license_url = 16;
  // verified indicates the plugin has been verified. Verification is a property
  // of the BSR and cannot be set by end-users.
  bool verified = 17;
  // Visibility indicates whether the plugin is public or private.
  CuratedPluginVisibility visibility = 18;
  // Deprecated indicates whether the plugin is deprecated.
  bool deprecated = 19;
  // Optionally specify a message to be displayed when the plugin is deprecated.
  string deprecation_message = 20;
}

// PluginCurationService manages curated plugins.
service PluginCurationService {
  // ListCuratedPlugins returns all the curated plugins available.
  rpc ListCuratedPlugins(ListCuratedPluginsRequest) returns (ListCuratedPluginsResponse) {
    option idempotency_level = NO_SIDE_EFFECTS;
  }
  // CreateCuratedPlugin creates a new curated plugin.
  rpc CreateCuratedPlugin(CreateCuratedPluginRequest) returns (CreateCuratedPluginResponse) {
    option idempotency_level = IDEMPOTENT;
  }
  // GetLatestCuratedPlugin returns the latest version of a plugin matching given parameters.
  rpc GetLatestCuratedPlugin(GetLatestCuratedPluginRequest) returns (GetLatestCuratedPluginResponse) {
    option idempotency_level = NO_SIDE_EFFECTS;
  }
  // DeleteCuratedPlugin deletes a curated plugin based on the given parameters.
  rpc DeleteCuratedPlugin(DeleteCuratedPluginRequest) returns (DeleteCuratedPluginResponse) {
    option idempotency_level = IDEMPOTENT;
  }
}

// CodeGenerationService generates code using remote plugins.
service CodeGenerationService {
  // GenerateCode generates code using the specified remote plugins.
  rpc GenerateCode(GenerateCodeRequest) returns (GenerateCodeResponse);
}

message GenerateCodeRequest {
  // The image to run plugins against to generate the desired file outputs.
  //
  // All image files that are not imports and not well-known types will be generated.
  // If you want to filter what files are generated, modify the image.
  // If you want to include imports, set include_imports.
  bufman.dubbo.apache.org.image.v1.Image image = 1;
  repeated PluginGenerationRequest requests = 2;
  // Include imports from the Image in generation. If include_imports is also set
  // in one of requests, use the request's value for that plugin.
  bool include_imports = 3;
  // Include Well-Known Types from the Image in generation.
  //
  // include_imports must be set if include_well_known_types is set. If include_well_known_types
  // is also set in one of requests, use the request's value for that plugin.
  bool include_well_known_types = 4;
}

message GenerateCodeResponse {
  // Responses from each plugin execution.
  // The order of each response matches the order in the GenerateCodeRequest.
  repeated PluginGenerationResponse responses = 1;
}

// Request for performing code generation using the specified plugin.
message PluginGenerationRequest {
  // The plugin to execute.
  CuratedPluginReference plugin_reference = 1;
  // The options to pass to the plugin. These will
  // be merged into a single, comma-separated string.
  repeated string options = 2;
  // Include imports from the Image in generation.
  optional bool include_imports = 3;
  // Include Well-Known Types from the Image in generation.
  //
  // include_imports must be set if include_well_known_types is set.
  optional bool include_well_known_types = 4;
}

// Response from code generation for a given plugin.
message PluginGenerationResponse {
  // Generated code from the plugin.
  google.protobuf.compiler.CodeGeneratorResponse response = 1;
}

message DeleteCuratedPluginRequest {
  // The owner of the plugin to delete.
  string owner = 1;
  // The name of the plugin to delete.
  string name = 2;
  // Version is the plugin version and is optional. If this field is not set then delete all versions,
  // otherwise delete only the specified version which includes all revisions.
  string version = 3;
}

message DeleteCuratedPluginResponse {}

message CreateCuratedPluginRequest {
  // The owner of the plugin, i.e. "library".
  string owner = 1;
  // The name of the plugin, i.e. "connect-go".
  string name = 2;
  // The optional registry type of the plugin.
  PluginRegistryType registry_type = 3;
  // Semver-formatted plugin version.
  string version = 4;
  // Image Name and Image Digest define a unique plugin image
  // Image Digest is like sha256:febcf61cd6e1ac9628f6ac14fa40836d16f3c6ddef3b303ff0321606e55ddd0b
  string image_digest = 5;
  // List of plugin dependencies.
  repeated CuratedPluginReference dependencies = 7;
  // The URL leading to the source code of the plugin, if available.
  string source_url = 8;
  // A brief description of the plugin functionality.
  string description = 9;
  // The configuration for the remote registry of the plugin.
  RegistryConfig registry_config = 12;
  // The revision for this plugin version.
  uint32 revision = 13;
  // The output languages supported by the plugin.
  repeated PluginLanguage output_languages = 14;
  // spdx_license_id is the license of the plugin, which should be one of the identifiers
  // defined in https://spdx.org/licenses
  string spdx_license_id = 15;
  // license_url specifies an optional URL for the plugin's license (if not using a standard spdx_license_id).
  string license_url = 16;
  // Visibility indicates whether the plugin is public or private.
  CuratedPluginVisibility visibility = 17;
  // Image Name and Image Digest define a unique plugin image
  string image_name = 18;
  // Docker Repo Name is define to access user's docker hub
  string docker_repo_name = 19;
}

message CreateCuratedPluginResponse {
  // The created plugin.
  CuratedPlugin configuration = 1;
}

message ListCuratedPluginsRequest {
  uint32 page_size = 1;
  // The first page is returned if this is empty.
  string page_token = 2;
  bool reverse = 3;
  // If true, will only return plugins which support remote packages (registry_type is set).
  bool supports_remote_packages = 4;
  // If true, will include deprecated plugins.
  bool include_deprecated = 5;
}

message ListCuratedPluginsResponse {
  repeated CuratedPlugin plugins = 1;
  // There are no more pages if this is empty.
  string next_page_token = 2;
}

message GetLatestCuratedPluginRequest {
  // The owner of the plugin, i.e. "library".
  string owner = 1;
  // The name of the plugin, i.e. "connect-go".
  string name = 2;
  // Both version (semver-formatted) and revision are optional, which means
  // return the latest plugin.
  // If version is set, but revision is omitted, then return the latest
  // revision for that version.
  // If version and revision are both set, return specific plugin.
  // It is an error to set a revision without a corresponding version.
  string version = 3;
  uint32 revision = 4;
  // If true, will only return versions (and revisions) which support remote packages (registry_type is set).
  bool supports_remote_packages = 5;
}

message GetLatestCuratedPluginResponse {
  CuratedPlugin plugin = 1;
  // versions is a semver-sorted list in descending order.
  repeated CuratedPluginVersionRevisions versions = 2;
}

message CuratedPluginVersionRevisions {
  string version = 1;
  // revisions is a sorted list in descending order.
  repeated uint32 revisions = 2;
}