tooling

Documentation

Overview

Package tooling provides schema parsing, code generation, and migration utilities for melange authorization. This package depends on OpenFGA for schema parsing, so it's separated from the core melange package to keep runtime dependencies minimal.

Users who only need runtime permission checking should import "github.com/pthm/melange" directly. Users who need programmatic schema parsing or migration should import this package.

Index

• func ConvertProtoModel(model *openfgav1.AuthorizationModel) []schema.TypeDefinition
• func GenerateGo(w io.Writer, types []schema.TypeDefinition, cfg *GenerateConfig) error
• func Migrate(ctx context.Context, db schema.Execer, schemasDir string) error
• func MigrateFromString(ctx context.Context, db schema.Execer, content string) error
• func MigrateWithOptions(ctx context.Context, db schema.Execer, schemasDir string, opts MigrateOptions) (skipped bool, err error)
• func ParseSchema(path string) ([]schema.TypeDefinition, error)
• func ParseSchemaString(content string) ([]schema.TypeDefinition, error)
• type GenerateConfig
  • func DefaultGenerateConfig() *GenerateConfig
• type MigrateOptions

Functions

func ConvertProtoModel

func ConvertProtoModel(model *openfgav1.AuthorizationModel) []schema.TypeDefinition

ConvertProtoModel converts an OpenFGA protobuf AuthorizationModel to schema TypeDefinitions. This is useful when you have a protobuf model directly (e.g., from the OpenFGA API) rather than DSL text.

This function is used by the OpenFGA test suite adapter to convert test models without re-implementing the parsing logic.

func GenerateGo

func GenerateGo(w io.Writer, types []schema.TypeDefinition, cfg *GenerateConfig) error

GenerateGo writes Go code for the types and relations from a parsed schema. This is a convenience re-export of schema.GenerateGo.

The generated code includes:

• ObjectType constants (TypeUser, TypeRepository, etc.)
• Relation constants (RelCanRead, RelOwner, etc.)
• Constructor functions (User(id), Repository(id), etc.)
• Wildcard constructors (AnyUser(), AnyRepository(), etc.)

Example:

types, _ := tooling.ParseSchema("schemas/schema.fga")
f, _ := os.Create("internal/authz/schema_gen.go")
tooling.GenerateGo(f, types, &tooling.GenerateConfig{
    Package: "authz",
    IDType:  "int64",
})

func Migrate

func Migrate(ctx context.Context, db schema.Execer, schemasDir string) error

Migrate is a convenience function that parses a schema file and applies it to the database. This combines ParseSchema + schema.ToAuthzModels + schema.MigrateWithTypes into a single operation.

The migration process:

1. Reads schemasDir/schema.fga
2. Parses OpenFGA DSL using the official parser
3. Validates schema (detects cycles)
4. Applies DDL (creates tables and functions)
5. Converts to authorization models and loads into PostgreSQL

For more control over the migration process, use the individual functions:

types, err := tooling.ParseSchema(path)
models := schema.ToAuthzModels(types)
migrator := schema.NewMigrator(db, schemasDir)
err = migrator.MigrateWithTypes(ctx, types)

The migration is idempotent and transactional (when using *sql.DB). Safe to run on application startup.

func MigrateFromString

func MigrateFromString(ctx context.Context, db schema.Execer, content string) error

MigrateFromString parses schema content and applies it to the database. Useful for testing or when schema is embedded in the application binary.

This allows bundling the authorization schema with the application rather than reading from disk, which simplifies deployment and versioning.

Example:

//go:embed schema.fga
var embeddedSchema string

err := tooling.MigrateFromString(ctx, db, embeddedSchema)

The migration is idempotent and transactional (when using *sql.DB).

func MigrateWithOptions

func MigrateWithOptions(ctx context.Context, db schema.Execer, schemasDir string, opts MigrateOptions) (skipped bool, err error)

MigrateWithOptions is like Migrate but with additional options for dry-run, force, and skip-if-unchanged behavior.

Returns (skipped, error) where skipped is true if migration was skipped because the schema is unchanged (and Force is false).

func ParseSchema

func ParseSchema(path string) ([]schema.TypeDefinition, error)

ParseSchema reads an OpenFGA .fga file and returns type definitions. Uses the official OpenFGA language parser to ensure compatibility with the OpenFGA ecosystem and tooling.

The parser extracts type definitions, relations, and metadata that are then converted to melange's internal representation for code generation and database migration.

func ParseSchemaString

func ParseSchemaString(content string) ([]schema.TypeDefinition, error)

ParseSchemaString parses OpenFGA DSL content and returns type definitions. This is the core parser used by both file-based and string-based parsing. Wraps the OpenFGA transformer to convert protobuf models to our format.

Types

type GenerateConfig

type GenerateConfig = schema.GenerateConfig

GenerateConfig is an alias for schema.GenerateConfig. This allows users of the tooling package to configure code generation without importing the schema package separately.

func DefaultGenerateConfig

func DefaultGenerateConfig() *GenerateConfig

DefaultGenerateConfig returns sensible defaults for code generation. Package: "authz", no relation filter (all relations), string IDs.

type MigrateOptions

type MigrateOptions struct {
	// DryRun outputs SQL to the provided writer without applying changes.
	// If nil, migration proceeds normally.
	DryRun io.Writer

	// Force re-runs migration even if schema/codegen unchanged.
	Force bool
}

MigrateOptions controls migration behavior.