libregistry

README

Go library for the OpenTofu registry

[!WARNING] This library is experimental.

This Go library implements the OpenTofu registry and also provides a library to access the underlying data. You can install this library by running:

go get github.com/opentofu/libregistry

The metadata API

The metadata API is a low-level API that allows you to access the stored registry data structure in the registry repository. Use this API when you need to work with the registry data without needing online functions, such as refreshing a module or provider.

You can use the metadata API like this:

package main

import (
    "context"

    "github.com/opentofu/libregistry/metadata"
    "github.com/opentofu/libregistry/metadata/storage/filesystem"
)

func main() {
    metadataAPI, err := metadata.New(filesystem.New("path/to/registry/data"))
    if err != nil {
        panic(err)
    }
    modules, err := metadataAPI.ListModules(context.Background())
    if err != nil {
        panic(err)
    }

    // Do something with modules here.
}

The registry API

The libregistry package contains the top level registry API. It implements the functions that are triggered from GitHub Actions, such as adding a module, etc.

You can use the registry API like this:

package main

import (
	"context"
	"os"

	"github.com/opentofu/libregistry"
	"github.com/opentofu/libregistry/metadata"
	"github.com/opentofu/libregistry/metadata/storage/filesystem"
	"github.com/opentofu/libregistry/vcs/github"
)

func main() {
	// github.New has more options, check the github package for details.
	ghClient, err := github.New(github.WithToken(os.Getenv("GITHUB_TOKEN")))
	if err != nil {
		panic(err)
	}

	storage := filesystem.New("path/to/registry/data")

	metadataAPI, err := metadata.New(storage)
	if err != nil {
		panic(err)
	}

	registry, err := libregistry.New(
		ghClient,
		metadataAPI,
	)
	if err != nil {
		panic(err)
	}

	if err := registry.AddModule(context.TODO(), "terraform-aws-modules/terraform-aws-iam"); err != nil {
		panic(err)
	}
}

VCS implementations

This library supports pluggable VCS systems. We run on GitHub by default, but you may be interested in implementing a VCS backend for a different system. Check out the vcs package for the VCS interface. Note, that the implementation still assumes that you will have an organization/repository structure and many systems, such as the registry UI, still assume that the VCS system will be git.

Metadata storage

You may also be interested in storing the metadata somewhere else than the local filesystem. For this purpose, check out the metadata/storage package, which contains the interface for defining storages.

Documentation

Index

• type API
  • func New(vcsClient vcs.Client, dataAPI metadata.ModuleDataAPI) (API, error)
• type ModuleAddFailedError
  • func (m ModuleAddFailedError) Error() string
  • func (m ModuleAddFailedError) Unwrap() error
• type ModuleAlreadyExistsError
  • func (m ModuleAlreadyExistsError) Error() string
• type ModuleUpdateFailedError
  • func (m ModuleUpdateFailedError) Error() string
  • func (m ModuleUpdateFailedError) Unwrap() error

Types

type API

type API interface {
	// AddModule adds a module based on a VCS repository. The VCS repository name must follow the naming convention
	// of the VCS implementation passed to the registry API on initialization.
	AddModule(ctx context.Context, vcsRepository string) error
	// UpdateModule updates the list of available versions for a module in the registry from its source repository.
	// This function is idempotent and adds the module to the storage if it does not exist yet.
	UpdateModule(ctx context.Context, moduleAddr module.Addr) error
}

API describes the API interface for accessing the registry.

func New

func New(vcsClient vcs.Client, dataAPI metadata.ModuleDataAPI) (API, error)

New creates a new instance of the registry API with the given GitHub client and data API instance.

type ModuleAddFailedError

type ModuleAddFailedError struct {
	Module module.Addr
	Cause  error
}

func (ModuleAddFailedError) Error

func (m ModuleAddFailedError) Error() string

func (ModuleAddFailedError) Unwrap

func (m ModuleAddFailedError) Unwrap() error

type ModuleAlreadyExistsError

type ModuleAlreadyExistsError struct {
	Module module.Addr
}

func (ModuleAlreadyExistsError) Error

func (m ModuleAlreadyExistsError) Error() string

type ModuleUpdateFailedError

type ModuleUpdateFailedError struct {
	Module module.Addr
	Cause  error
}

func (ModuleUpdateFailedError) Error

func (m ModuleUpdateFailedError) Error() string

func (ModuleUpdateFailedError) Unwrap

func (m ModuleUpdateFailedError) Unwrap() error