feat: implement release-init container contract (#1677)

Fixes #1011

Author: JoeWang1127

internal/config/config.go

@@ -45,6 +45,8 @@ const (
 	// LibrarianDir is the default directory to store librarian state/config files,
 	// along with any additional configuration.
 	LibrarianDir = ".librarian"
+	// ReleaseInitRequest is a JSON file that describes which library to release.
+	ReleaseInitRequest = "release-init-request.json"
 )
 
 // Config holds all configuration values parsed from flags or environment
@@ -118,6 +120,16 @@ type Config struct {
 	// api is specified all currently managed libraries will be regenerated.
 	Library string
 
+	// LibraryVersion is the library version to release.
+	//
+	// Overrides the automatic semantic version calculation and forces a specific
+	// version for a library.
+	// This is intended for exceptional cases, such as applying a backport patch
+	// or forcing a major version bump.
+	//
+	// Requires the --library flag to be specified.
+	LibraryVersion string
+
 	// Push determines whether to push changes to GitHub. It is used in
 	// all commands that create commits in a language repository:
 	// configure and update-apis.
@@ -206,6 +218,10 @@ func (c *Config) IsValid() (bool, error) {
 		return false, errors.New("no GitHub token supplied for push")
 	}
 
+	if c.Library == "" && c.LibraryVersion != "" {
+		return false, errors.New("specified library version without library id")
+	}
+
 	if _, err := validateHostMount(c.HostMount, ""); err != nil {
 		return false, err
 	}

internal/config/config_test.go

@@ -17,6 +17,7 @@ package config
 import (
 	"errors"
 	"os/user"
+	"strings"
 	"testing"
 
 	"github.com/google/go-cmp/cmp"
@@ -128,81 +129,88 @@ func TestSetupUser(t *testing.T) {
 
 func TestIsValid(t *testing.T) {
 	for _, test := range []struct {
-		name      string
-		cfg       Config
-		wantValid bool
-		wantErr   bool
+		name       string
+		cfg        Config
+		wantErr    bool
+		wantErrMsg string
 	}{
 		{
 			name: "Valid config - Push false",
 			cfg: Config{
 				Push:        false,
 				GitHubToken: "",
 			},
-			wantValid: true,
-			wantErr:   false,
 		},
 		{
 			name: "Valid config - Push true, token present",
 			cfg: Config{
 				Push:        true,
 				GitHubToken: "some_token",
 			},
-			wantValid: true,
-			wantErr:   false,
+		},
+		{
+			name: "Valid config - missing library version",
+			cfg: Config{
+				Push:        true,
+				GitHubToken: "some_token",
+				Library:     "library-id",
+			},
 		},
 		{
 			name: "Invalid config - Push true, token missing",
 			cfg: Config{
 				Push:        true,
 				GitHubToken: "",
 			},
-			wantValid: false,
-			wantErr:   true,
+			wantErr:    true,
+			wantErrMsg: "no GitHub token supplied for push",
+		},
+		{
+			name: "Invalid config - library version presents, missing library id",
+			cfg: Config{
+				Push:           true,
+				GitHubToken:    "some_token",
+				LibraryVersion: "1.2.3",
+			},
+			wantErr:    true,
+			wantErrMsg: "specified library version without library id",
 		},
 		{
 			name: "Invalid config - host mount invalid, missing local-dir",
 			cfg: Config{
 				Push:      false,
 				HostMount: "host-dir:",
 			},
-			wantValid: false,
-			wantErr:   true,
+			wantErr:    true,
+			wantErrMsg: "unable to parse host mount",
 		},
 		{
 			name: "Invalid config - host mount invalid, missing host-dir",
 			cfg: Config{
 				Push:      false,
 				HostMount: ":local-dir",
 			},
-			wantValid: false,
-			wantErr:   true,
+			wantErr:    true,
+			wantErrMsg: "unable to parse host mount",
 		},
 		{
 			name: "Invalid config - host mount invalid, missing separator",
 			cfg: Config{
 				Push:      false,
 				HostMount: "host-dir/local-dir",
 			},
-			wantValid: false,
-			wantErr:   true,
+			wantErr:    true,
+			wantErrMsg: "unable to parse host mount",
 		},
 	} {
 		t.Run(test.name, func(t *testing.T) {
 			gotValid, err := test.cfg.IsValid()
 
-			if gotValid != test.wantValid {
-				t.Errorf("IsValid() got valid = %t, want %t", gotValid, test.wantValid)
+			if gotValid != !test.wantErr {
+				t.Errorf("IsValid() got valid = %t, want %t", gotValid, !test.wantErr)
 			}
 
-			if (err != nil) != test.wantErr {
-				t.Errorf("IsValid() got error = %v, want error = %t", err, test.wantErr)
-			}
-			if test.wantErr &&
-				err != nil &&
-				err.Error() != "no GitHub token supplied for push" &&
-				err.Error() != "unable to parse push config" &&
-				err.Error() != "unable to parse host mount" {
+			if test.wantErr && !strings.Contains(err.Error(), test.wantErrMsg) {
 				t.Errorf("IsValid() got unexpected error message: %q", err.Error())
 			}
 		})

internal/config/state.go

@@ -24,9 +24,9 @@ import (
 // LibrarianState defines the contract for the state.yaml file.
 type LibrarianState struct {
 	// The name and tag of the generator image to use. tag is required.
-	Image string `yaml:"image"`
+	Image string `yaml:"image" json:"image"`
 	// A list of library configurations.
-	Libraries []*LibraryState `yaml:"libraries"`
+	Libraries []*LibraryState `yaml:"libraries" json:"libraries"`
 }
 
 // Validate checks that the LibrarianState is valid.

internal/docker/docker.go

@@ -37,12 +37,14 @@ type Command string
 
 // The set of commands passed to the language container, in a single place to avoid typos.
 const (
-	// CommandGenerate performs generation for a configured library.
-	CommandGenerate Command = "generate"
 	// CommandBuild builds a library.
 	CommandBuild Command = "build"
 	// CommandConfigure configures a new API as a library.
 	CommandConfigure Command = "configure"
+	// CommandGenerate performs generation for a configured library.
+	CommandGenerate Command = "generate"
+	// CommandReleaseInit performs release for a library.
+	CommandReleaseInit Command = "release-init"
 )
 
 // Docker contains all the information required to run language-specific
@@ -61,44 +63,41 @@ type Docker struct {
 	run func(args ...string) error
 }
 
-// GenerateRequest contains all the information required for a language
-// container to run the generate command.
-type GenerateRequest struct {
+// BuildRequest contains all the information required for a language
+// container to run the build command.
+type BuildRequest struct {
 	// cfg is a pointer to the [config.Config] struct, holding general configuration
 	// values parsed from flags or environment variables.
 	Cfg *config.Config
 	// state is a pointer to the [config.LibrarianState] struct, representing
 	// the overall state of the generation and release pipeline.
 	State *config.LibrarianState
-	// apiRoot specifies the root directory of the API specification repo.
-	ApiRoot string
-	// libraryID specifies the ID of the library to generate
+	// libraryID specifies the ID of the library to build.
 	LibraryID string
-	// output specifies the empty output directory into which the command should
-	// generate code
-	Output string
 	// RepoDir is the local root directory of the language repository.
 	RepoDir string
 }
 
-// BuildRequest contains all the information required for a language
-// container to run the build command.
-type BuildRequest struct {
+// ConfigureRequest contains all the information required for a language
+// container to run the configure command.
+type ConfigureRequest struct {
 	// cfg is a pointer to the [config.Config] struct, holding general configuration
 	// values parsed from flags or environment variables.
 	Cfg *config.Config
 	// state is a pointer to the [config.LibrarianState] struct, representing
 	// the overall state of the generation and release pipeline.
 	State *config.LibrarianState
-	// libraryID specifies the ID of the library to build
+	// apiRoot specifies the root directory of the API specification repo.
+	ApiRoot string
+	// libraryID specifies the ID of the library to configure.
 	LibraryID string
 	// RepoDir is the local root directory of the language repository.
 	RepoDir string
 }
 
-// ConfigureRequest contains all the information required for a language
-// container to run the configure command.
-type ConfigureRequest struct {
+// GenerateRequest contains all the information required for a language
+// container to run the generate command.
+type GenerateRequest struct {
 	// cfg is a pointer to the [config.Config] struct, holding general configuration
 	// values parsed from flags or environment variables.
 	Cfg *config.Config
@@ -107,8 +106,31 @@ type ConfigureRequest struct {
 	State *config.LibrarianState
 	// apiRoot specifies the root directory of the API specification repo.
 	ApiRoot string
-	// libraryID specifies the ID of the library to generate
+	// libraryID specifies the ID of the library to generate.
 	LibraryID string
+	// output specifies the empty output directory into which the command should
+	// generate code
+	Output string
+	// RepoDir is the local root directory of the language repository.
+	RepoDir string
+}
+
+// ReleaseRequest contains all the information required for a language
+// container to run the release command.
+type ReleaseRequest struct {
+	// cfg is a pointer to the [config.Config] struct, holding general configuration
+	// values parsed from flags or environment variables.
+	Cfg *config.Config
+	// state is a pointer to the [config.LibrarianState] struct, representing
+	// the overall state of the generation and release pipeline.
+	State *config.LibrarianState
+	// libraryID specifies the ID of the library to release.
+	LibraryID string
+	// libraryID specifies the version of the library to release.
+	LibraryVersion string
+	// output specifies the empty output directory into which the command should
+	// generate code
+	Output string
 	// RepoDir is the local root directory of the language repository.
 	RepoDir string
 }
@@ -132,7 +154,7 @@ func New(workRoot, image, uid, gid string) (*Docker, error) {
 // library.
 func (c *Docker) Generate(ctx context.Context, request *GenerateRequest) error {
 	jsonFilePath := filepath.Join(request.RepoDir, config.LibrarianDir, config.GenerateRequest)
-	if err := writeRequest(request.State, request.LibraryID, jsonFilePath); err != nil {
+	if err := writeLibraryState(request.State, request.LibraryID, jsonFilePath); err != nil {
 		return err
 	}
 	defer func(name string) {
@@ -165,7 +187,7 @@ func (c *Docker) Generate(ctx context.Context, request *GenerateRequest) error {
 // the Librarian state file for the repository with a root of repoRoot.
 func (c *Docker) Build(ctx context.Context, request *BuildRequest) error {
 	jsonFilePath := filepath.Join(request.RepoDir, config.LibrarianDir, config.BuildRequest)
-	if err := writeRequest(request.State, request.LibraryID, jsonFilePath); err != nil {
+	if err := writeLibraryState(request.State, request.LibraryID, jsonFilePath); err != nil {
 		return err
 	}
 	defer func(name string) {
@@ -194,7 +216,7 @@ func (c *Docker) Build(ctx context.Context, request *BuildRequest) error {
 // Returns the configured library id if the command succeeds.
 func (c *Docker) Configure(ctx context.Context, request *ConfigureRequest) (string, error) {
 	requestFilePath := filepath.Join(request.RepoDir, config.LibrarianDir, config.ConfigureRequest)
-	if err := writeRequest(request.State, request.LibraryID, requestFilePath); err != nil {
+	if err := writeLibraryState(request.State, request.LibraryID, requestFilePath); err != nil {
 		return "", err
 	}
 	defer func() {
@@ -223,6 +245,44 @@ func (c *Docker) Configure(ctx context.Context, request *ConfigureRequest) (stri
 	return request.LibraryID, nil
 }
 
+// ReleaseInit initiates a release for a given language repository.
+func (c *Docker) ReleaseInit(ctx context.Context, request *ReleaseRequest) error {
+	requestFilePath := filepath.Join(request.RepoDir, config.LibrarianDir, config.ReleaseInitRequest)
+	if err := writeLibrarianState(request.State, requestFilePath); err != nil {
+		return err
+	}
+	defer func() {
+		err := os.Remove(requestFilePath)
+		if err != nil {
+			slog.Warn("fail to remove file", slog.String("name", requestFilePath), slog.Any("err", err))
+		}
+	}()
+	commandArgs := []string{
+		"--librarian=/librarian",
+		"--repo=/repo",
+		"--output=/output",
+	}
+	if request.LibraryID != "" {
+		commandArgs = append(commandArgs, fmt.Sprintf("--library=%s", request.LibraryID))
+	}
+	if request.LibraryVersion != "" {
+		commandArgs = append(commandArgs, fmt.Sprintf("--library-version=%s", request.LibraryVersion))
+	}
+
+	librarianDir := filepath.Join(request.RepoDir, config.LibrarianDir)
+	mounts := []string{
+		fmt.Sprintf("%s:/librarian", librarianDir),
+		fmt.Sprintf("%s:/repo:ro", request.RepoDir), // readonly volume
+		fmt.Sprintf("%s:/output", request.Output),
+	}
+
+	if err := c.runDocker(ctx, request.Cfg, CommandReleaseInit, mounts, commandArgs); err != nil {
+		return err
+	}
+
+	return nil
+}
+
 func (c *Docker) runDocker(_ context.Context, cfg *config.Config, command Command, mounts []string, commandArgs []string) (err error) {
 	mounts = maybeRelocateMounts(cfg, mounts)
 
@@ -277,13 +337,13 @@ func (c *Docker) runCommand(cmdName string, args ...string) error {
 	return err
 }
 
-func writeRequest(state *config.LibrarianState, libraryID, jsonFilePath string) error {
+func writeLibraryState(state *config.LibrarianState, libraryID, jsonFilePath string) error {
 	if err := os.MkdirAll(filepath.Dir(jsonFilePath), 0755); err != nil {
 		return fmt.Errorf("failed to make directory: %w", err)
 	}
 	jsonFile, err := os.Create(jsonFilePath)
 	if err != nil {
-		return fmt.Errorf("failed to create generate request JSON file: %w", err)
+		return fmt.Errorf("failed to create JSON file: %w", err)
 	}
 	defer jsonFile.Close()
 
@@ -304,3 +364,23 @@ func writeRequest(state *config.LibrarianState, libraryID, jsonFilePath string)
 
 	return nil
 }
+
+func writeLibrarianState(state *config.LibrarianState, jsonFilePath string) error {
+	if err := os.MkdirAll(filepath.Dir(jsonFilePath), 0755); err != nil {
+		return fmt.Errorf("failed to make directory: %w", err)
+	}
+	jsonFile, err := os.Create(jsonFilePath)
+	if err != nil {
+		return fmt.Errorf("failed to create JSON file: %w", err)
+	}
+	defer jsonFile.Close()
+
+	data, err := json.MarshalIndent(state, "", "  ")
+	if err != nil {
+		return fmt.Errorf("failed to marshal state to JSON: %w", err)
+	}
+
+	_, err = jsonFile.Write(data)
+
+	return err
+}