pkg/bufman/proto/registry/v1alpha1/generate.proto

syntax = "proto3";

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

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

// replaced with CodeGenerationService in plugin_curation.proto.
option deprecated = true;

// File defines a file with a path and some content.
message File {
  // path is the relative path of the file.
  // Path can only use '/' as the separator character, and includes no ".." components.
  string path = 1;
  // content is the content of the file.
  bytes content = 2;
}

// RuntimeLibrary describes a pinned runtime library dependency of the generated code.
message RuntimeLibrary {
  // The name of the runtime library dependency. The format should match the
  // format used for dependencies in the dependency management tooling of the
  // associated language ecosystem. This is set by the user using Dockerfile Labels.
  // For example, for the plugin "protoc-gen-go", this might be "google.golang.org/protobuf".
  string name = 1;
  // The version of the runtime library dependency associated with the generated
  // code. The format should match the format used for dependency versions in the
  // dependency management tooling of the associated language ecosystem.
  // This is set by the user using Dockerfile Labels.
  // For example, for the plugin "protoc-gen-go", this might be "v1.26.0".
  string version = 2;
}

message PluginReference {
  // The owner of the plugin which identifies the
  // plugins to use with this generation.
  string owner = 1;
  // The name of the plugin which identifies the
  // plugins to use with this generation.
  string name = 2;
  // The plugin version to use with this generation.
  string version = 3;
  // The parameters to pass to the plugin. These will
  // be merged into a single, comma-separated string.
  repeated string parameters = 4;
}

// GenerateService manages remote generation requests.
service GenerateService {
  // GeneratePlugins generates an array of files given the provided
  // module reference and plugin version and option tuples. No attempt
  // is made at merging insertion points.
  rpc GeneratePlugins(GeneratePluginsRequest) returns (GeneratePluginsResponse);
  // GenerateTemplate generates an array of files given the provided
  // module reference and template version.
  rpc GenerateTemplate(GenerateTemplateRequest) returns (GenerateTemplateResponse);
}

message GeneratePluginsRequest {
  // 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;
  // The array of plugins to use.
  repeated PluginReference plugins = 2;
  // Include imports from the Image in generation.
  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.
  bool include_well_known_types = 4;
}

message GeneratePluginsResponse {
  // Contains all the responses from the generated plugins. The order
  // is defined by the order of the plugins in the request.
  repeated google.protobuf.compiler.CodeGeneratorResponse responses = 1;
  // An optional array defining runtime libraries that the generated code
  // requires to run, as specified by the plugin author. This may contain
  // duplicate entries as the generation can be the result of multiple plugins,
  // each of which declares its own runtime library dependencies. The libraries
  // returned are lexicographically ordered by their name, but not deduplicated.
  // How to handle duplicate libraries is left to the user.
  repeated RuntimeLibrary runtime_libraries = 2;
}

message GenerateTemplateRequest {
  // 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;
  // The owner of the template which identifies the
  // plugins to use with this generation.
  string template_owner = 2;
  // The name of the template which identifies the
  // plugins to use with this generation.
  string template_name = 3;
  // The template version to use to determine the
  // plugin versions in the template.
  string template_version = 4;
  // Include imports from the Image in generation.
  bool include_imports = 5;
  // Include Well-Known Types from the Image in generation.
  //
  // include_imports must be set if include_well_known_types is set.
  bool include_well_known_types = 6;
}

message GenerateTemplateResponse {
  // files contains all the files output by the generation,
  // in lexicographical order.
  repeated File files = 1;
  // An optional array defining runtime libraries that the generated code
  // requires to run. This may contain duplicate entries as the generation
  // can be the result of multiple plugins, each of which declares its own
  // runtime library dependencies.
  repeated RuntimeLibrary runtime_libraries = 2;
}