melange

type AuthzModel ¶

type AuthzModel struct {
	ID               int64
	ObjectType       string  // Object type this rule applies to
	Relation         string  // Relation this rule defines
	SubjectType      *string // Allowed subject type (for direct rules)
	ImpliedBy        *string // Implying relation (for role hierarchy)
	ParentRelation   *string // Parent relation to check (for inheritance)
	ExcludedRelation *string // Relation to exclude (for "but not" rules)
}

AuthzModel represents an entry in the melange_model table. Each row defines one authorization rule that check_permission evaluates.

The table stores the flattened authorization model, precomputing transitive closures and normalizing rules for efficient query execution.

Rule types:

• Direct: SubjectType is set, others NULL (user can have relation)
• Implied: ImpliedBy is set (having one relation grants another)
• Parent: ParentRelation and SubjectType set (inherit from parent object)
• Exclusive: ExcludedRelation set (permission denied if exclusion holds)

func ToAuthzModels(types []TypeDefinition) []AuthzModel

type Cache ¶

type Cache interface {
	// Get retrieves a cached permission check result.
	// Returns (allowed, err, found). If found is false, the entry doesn't exist or is expired.
	Get(subject Object, relation Relation, object Object) (allowed bool, err error, ok bool)

	// Set stores a permission check result in the cache.
	Set(subject Object, relation Relation, object Object, allowed bool, err error)
}

Cache stores permission check results. It is safe for concurrent use from multiple goroutines.

Implementations should cache both allowed and denied permissions, including errors. This reduces database load for repeated checks of denied access.

type CacheImpl ¶

type CacheImpl struct {
	// contains filtered or unexported fields
}

CacheImpl is the default in-memory cache implementation with optional TTL. It uses a sync.RWMutex for goroutine safety. For high-contention scenarios, consider a sharded cache or external cache (Redis, etc.).

The cache grows unbounded within its TTL window. For long-running processes with large permission sets, consider periodic clearing or TTL-based expiry.

func NewCache(opts ...CacheOption) *CacheImpl

func (c *CacheImpl) Clear()

func (c *CacheImpl) Get(subject Object, relation Relation, object Object) (bool, error, bool)

func (c *CacheImpl) Set(subject Object, relation Relation, object Object, allowed bool, err error)

func (c *CacheImpl) Size() int

type CacheOption ¶

type CacheOption func(*CacheImpl)

CacheOption configures a Cache.

func WithTTL(ttl time.Duration) CacheOption

type Checker ¶

type Checker struct {
	// contains filtered or unexported fields
}

Checker performs authorization checks against PostgreSQL. It evaluates permissions using the melange_model table (parsed FGA schema) and the melange_tuples view (application data).

Checkers are lightweight and safe to create per-request. They hold no state beyond the database handle, cache, and decision override. The database handle can be *sql.DB, *sql.Tx, or *sql.Conn, allowing permission checks to see uncommitted changes within transactions.

Schema validation runs once per process on the first NewChecker call with a non-nil Querier. Validation issues are logged as warnings but do not prevent Checker creation, allowing applications to start even if the authorization schema is not yet fully configured.

func NewChecker(q Querier, opts ...Option) *Checker

func (c *Checker) Check(ctx context.Context, subject SubjectLike, relation RelationLike, object ObjectLike) (bool, error)

ok, err := checker.Check(ctx, authz.User("123"), authz.RelCanRead, authz.Repository("456"))

func (c *Checker) ListObjects(ctx context.Context, subject SubjectLike, relation RelationLike, objectType ObjectType) ([]string, error)

ids, _ := checker.ListObjects(ctx, authz.User("123"), authz.RelCanRead, authz.TypeRepository)

func (c *Checker) ListSubjects(ctx context.Context, object ObjectLike, relation RelationLike, subjectType ObjectType) ([]string, error)

ids, _ := checker.ListSubjects(ctx, authz.Repository("456"), authz.RelCanRead, authz.TypeUser)
// Returns IDs of all users who can read repository 456

func (c *Checker) Must(ctx context.Context, subject SubjectLike, relation RelationLike, object ObjectLike)

// After RequireAuth middleware ensures user is authenticated:
repo := getRepository(...)
checker.Must(ctx, authz.User(user.ID), authz.RelCanWrite, repo)
// Only reachable if permission granted

type Decision ¶

type Decision int

Decision allows bypassing DB checks for admin tools and tests. Decisions are set at Checker construction time via WithDecision, making the bypass explicit and visible in code.

const (
	// DecisionUnset means no override - perform normal permission check.
	DecisionUnset Decision = iota

	// DecisionAllow bypasses checks and always returns true (allowed).
	// Use for admin tools, background jobs, or testing authorized code paths.
	DecisionAllow

	// DecisionDeny bypasses checks and always returns false (denied).
	// Use for testing unauthorized code paths without database setup.
	DecisionDeny
)

func GetDecisionContext(ctx context.Context) Decision

type Execer ¶

type Execer interface {
	Querier
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
}

Execer extends Querier with ExecContext for migrations. Only required by the CLI migrate command, not for runtime permission checks. Separating this interface keeps the Checker dependency minimal.

type GenerateConfig ¶

type GenerateConfig struct {
	// Package name for generated code. Default: "authz"
	Package string

	// RelationPrefixFilter is a prefix filter for relation names.
	// Only relations with this prefix will have constants generated.
	// If empty, all relations will be generated.
	//
	// Example: "can_" generates only permission relations, omitting roles.
	RelationPrefixFilter string

	// IDType specifies the type to use for object IDs.
	// Default: "string"
	// The type must implement fmt.Stringer or be safely convertible to string.
	//
	// Common values: "string", "int64", "uuid.UUID"
	// The generated code uses fmt.Sprint(id) for conversion.
	IDType string
}

GenerateConfig configures code generation. The generator produces Go code with type-safe constants for object types and relations defined in the FGA schema.

func DefaultGenerateConfig() *GenerateConfig

type Migrator ¶

type Migrator struct {
	// contains filtered or unexported fields
}

Migrator handles loading authorization schemas into PostgreSQL. The migrator is idempotent - safe to run on every application startup.

The migration process:

1. Creates melange_model table (if not exists)
2. Creates/replaces check_permission and list_accessible_* functions
3. Loads pre-parsed authorization rules into the database

Usage with Tooling Module ¶

For most use cases, use the tooling module's convenience functions which handle parsing and migration in one step:

import "github.com/pthm/melange/tooling"
err := tooling.Migrate(ctx, db, "schemas")

Use the core Migrator directly when you have pre-parsed TypeDefinitions or need fine-grained control (DDL-only, status checks, etc.):

types, _ := tooling.ParseSchema("schemas/schema.fga")
migrator := melange.NewMigrator(db, "schemas")
err := migrator.MigrateWithTypes(ctx, types)

This separation keeps the core melange package free of OpenFGA dependencies.

func NewMigrator(db Execer, schemasDir string) *Migrator

func (m *Migrator) ApplyDDL(ctx context.Context) error

func (m *Migrator) GetStatus(ctx context.Context) (*Status, error)

func (m *Migrator) HasSchema() bool

func (m *Migrator) MigrateWithTypes(ctx context.Context, types []TypeDefinition) error

func (m *Migrator) SchemaPath() string

type Object ¶

type Object struct {
	Type ObjectType
	ID   string
}

Object represents a typed resource identifier. In FGA terms, both "users" and "resources" are objects - there's no distinction between subjects and objects at the type level.

Objects are value types and safe to copy. The canonical string format is "type:id", used in logging and debugging.

func (o Object) FGAObject() Object

func (o Object) FGASubject() Object

func (o Object) String() string

type ObjectLike ¶

type ObjectLike interface {
	FGAObject() Object
}

ObjectLike defines an interface for types that can be converted to Objects. This allows domain models to implement authorization-aware methods without importing the full domain layer into melange.

Example:

type Repository struct { ID int64; OwnerName string }
func (r Repository) FGAObject() melange.Object {
    return melange.Object{Type: "repository", ID: fmt.Sprint(r.ID)}
}

The Checker accepts ObjectLike rather than Object directly, enabling type-safe authorization checks against domain models.

type ObjectType ¶

type ObjectType string

ObjectType represents the type of an object.

func (ot ObjectType) String() string

type Option ¶

type Option func(*Checker)

Option configures a Checker.

func WithCache(c Cache) Option

func WithContextDecision() Option

func WithDecision(d Decision) Option

type Querier ¶

type Querier interface {
	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
}

Querier executes queries against PostgreSQL. Implemented by *sql.DB, *sql.Tx, and *sql.Conn.

The minimal interface allows Checker to work in transaction contexts without requiring a full database connection. This enables permission checks to see uncommitted changes within a transaction, supporting patterns like:

tx.Exec("INSERT INTO repositories ...")
// melange_tuples view reflects the new row
checker.Check(ctx, user, "can_read", repo) // sees new tuple
tx.Commit()

type Relation ¶

type Relation string

Relation represents a typed relation identifier. Relations can be permissions (can_read, can_write) or roles (owner, member). Unlike some authorization systems, melange treats all relations uniformly.

func (r Relation) FGARelation() Relation

func (r Relation) String() string

type RelationDefinition ¶

type RelationDefinition struct {
	Name             string   // Relation name: "owner", "can_read", etc.
	SubjectTypes     []string // Direct subject types: ["user"], ["organization"]
	ImpliedBy        []string // Relations that imply this one: ["owner", "admin"]
	ParentRelation   string   // For inheritance: "can_read from org" → "can_read"
	ParentType       string   // The relation linking to parent: "org", "repo"
	ExcludedRelation string   // For exclusions: "can_read but not author" → "author"
}

RelationDefinition represents a parsed relation. Relations describe who can have what relationship with an object.

A relation can be:

• Direct: explicitly granted via tuples (SubjectTypes)
• Implied: granted by having another relation (ImpliedBy)
• Inherited: derived from a parent object (ParentRelation, ParentType)
• Exclusive: granted except for excluded subjects (ExcludedRelation)

type RelationLike ¶

type RelationLike interface {
	FGARelation() Relation
}

RelationLike defines an interface for types that can be converted to Relations. This allows generated code to provide type-safe relation constants while accepting custom relation types from domain models.

type Status ¶

type Status struct {
	// SchemaExists indicates if the schema.fga file exists on disk.
	SchemaExists bool

	// ModelCount is the number of rows in the melange_model table.
	// Zero means the schema hasn't been loaded (run `melange migrate`).
	ModelCount int64
}

Status represents the current migration state. Use GetStatus to check if the authorization system is properly configured.

type SubjectLike ¶

type SubjectLike interface {
	FGASubject() Object
}

SubjectLike defines an interface for types that can be used as subjects. In FGA terms, subjects are the "who" in "who has what relation on what object". Subjects are typically users but can be any typed resource.

Example:

type User struct { ID int64; Username string }
func (u User) FGASubject() melange.Object {
    return melange.Object{Type: "user", ID: fmt.Sprint(u.ID)}
}

Note: Object implements both SubjectLike and ObjectLike, allowing melange.Object values to be used directly in either position.

type TypeDefinition ¶

type TypeDefinition struct {
	Name      string
	Relations []RelationDefinition
}

TypeDefinition represents a parsed type from an .fga file. Each type definition describes an object type (user, repository, etc.) and the relations that can exist on objects of that type.