ll

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 15, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

README

Carabiner Lamplight Client

This repository contains the client library for Carabiner's Lamplight service. Lamplight is Carabiner's permissions system. It is not open source (for now at least!), but the client is.

You are welcome to use this client to interact with the lamplight service in your own applications, but we recommend that if you develop an app that needs IAM capabilities you use the higher livel libraries of our SDK.

Documentation

Overview

Package ll provides a client for interacting with a Lamplight server.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DecodeID 

func DecodeID(s string) string

DecodeID URL-decodes an ID, reversing EncodeID.

func EncodeID 

func EncodeID(s string) string

EncodeID URL-encodes special characters in an ID that would conflict with tuple or path delimiters. Characters encoded: % @ # : >

func FormatTuple 

func FormatTuple(t *llv1.RelationTuple) string

FormatTuple formats a RelationTuple as a string. IDs are stored URL-encoded, so this returns the encoded form.

func FormatTupleDecoded 

func FormatTupleDecoded(t *llv1.RelationTuple) string

FormatTupleDecoded formats a RelationTuple as a string with decoded IDs. This is useful for human-readable display. IDs containing special characters are wrapped in quotes.

func ParseTuple 

func ParseTuple(s string) (*llv1.RelationTuple, error)

ParseTuple parses a string like "document:doc1#viewer@user:alice" into a RelationTuple. Supports quoted values for IDs containing special characters:

  • document:"doc@1"#viewer@user:alice
  • document:doc1#viewer@user:"bob@email.com"

Quoted values are URL-encoded in the resulting tuple. Already percent-encoded values are passed through as-is.

func ValidateEncodedID 

func ValidateEncodedID(s string) error

ValidateEncodedID checks that an ID is properly percent-encoded. Any '%' must be followed by exactly two hex digits.

func ValidateTuple 

func ValidateTuple(t *llv1.RelationTuple) error

ValidateTuple checks that a tuple has valid syntax and properly encoded IDs. It does not validate against a schema (that's done server-side).

Types

type Client 

type Client interface {
	Check(ctx context.Context, tuple *llv1.RelationTuple) (bool, error)
	Write(ctx context.Context, writes, deletes []*llv1.RelationTuple) error
	Read(ctx context.Context, filter *llv1.RelationTupleFilter) ([]*llv1.RelationTuple, error)
	Delete(ctx context.Context, filter *llv1.RelationTupleFilter) error
	ListObjects(ctx context.Context, subjectType, subjectID, permission, objectType string) ([]string, error)
	Expand(ctx context.Context, objectType, objectID, permission string) (*llv1.ExpandTree, error)
	WriteSchema(ctx context.Context, yamlData string) error
	ReadSchema(ctx context.Context) (string, error)
	ReadSchemaSet(ctx context.Context, name string) (string, error)
	ListSchemaSets(ctx context.Context) ([]string, error)
	DeleteSchemaSet(ctx context.Context, name string) error
	WhoAmI(ctx context.Context) (*llv1.WhoAmIResponse, error)
	// EnsurePath ensures all parent tuples exist for the given path.
	// The path format is: type:id>type:id>type:id#relation
	// This creates tuples connecting each child to its parent using the specified relation.
	EnsurePath(ctx context.Context, path string) error
	// CheckPath checks if all tuples in the given path exist.
	// Returns whether the path is complete and which tuples are found/missing.
	CheckPath(ctx context.Context, path string) (*llv1.CheckPathResponse, error)
	// GrantRole assigns a role to a subject on an object.
	GrantRole(ctx context.Context, role, objectType, objectID, subjectType, subjectID string) (*llv1.RoleAssignment, error)
	// RevokeRole removes a role assignment from a subject on an object.
	RevokeRole(ctx context.Context, role, objectType, objectID, subjectType, subjectID string) error
	// ListRoleAssignments returns all role assignments matching the filter.
	ListRoleAssignments(ctx context.Context, objectType, objectID, subjectType, subjectID, role string) ([]*llv1.RoleAssignment, error)
	// ListRoles returns the names of all defined roles.
	ListRoles(ctx context.Context) ([]string, error)
	Close() error
}

Client is the interface for interacting with a Lamplight server.

func New 

func New(serverAddr string, opts ...Option) (Client, error)

New creates a new Client connected to the given server address. By default, TLS is used for non-localhost addresses. Use WithInsecure() to disable TLS for local development.

func NewREST added in v0.2.0 

func NewREST(serverAddr string, opts ...RESTOption) (Client, error)

NewREST creates a new REST Client connected to the given server address. By default, HTTPS is used for non-localhost addresses. Use WithRESTInsecure() to force HTTP for local development.

type GRPCClient 

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

GRPCClient implements Client using gRPC.

func (*GRPCClient) Check 

func (c *GRPCClient) Check(ctx context.Context, t *llv1.RelationTuple) (bool, error)

func (*GRPCClient) CheckPath added in v0.2.0 

func (c *GRPCClient) CheckPath(ctx context.Context, pathStr string) (*llv1.CheckPathResponse, error)

func (*GRPCClient) Close 

func (c *GRPCClient) Close() error

func (*GRPCClient) Delete 

func (c *GRPCClient) Delete(ctx context.Context, filter *llv1.RelationTupleFilter) error

func (*GRPCClient) DeleteSchemaSet 

func (c *GRPCClient) DeleteSchemaSet(ctx context.Context, name string) error

func (*GRPCClient) EnsurePath added in v0.2.0 

func (c *GRPCClient) EnsurePath(ctx context.Context, pathStr string) error

func (*GRPCClient) Expand 

func (c *GRPCClient) Expand(ctx context.Context, objectType, objectID, permission string) (*llv1.ExpandTree, error)

func (*GRPCClient) GrantRole added in v0.2.0 

func (c *GRPCClient) GrantRole(ctx context.Context, role, objectType, objectID, subjectType, subjectID string) (*llv1.RoleAssignment, error)

func (*GRPCClient) ListObjects 

func (c *GRPCClient) ListObjects(ctx context.Context, subjectType, subjectID, permission, objectType string) ([]string, error)

func (*GRPCClient) ListRoleAssignments added in v0.2.0 

func (c *GRPCClient) ListRoleAssignments(ctx context.Context, objectType, objectID, subjectType, subjectID, role string) ([]*llv1.RoleAssignment, error)

func (*GRPCClient) ListRoles added in v0.2.0 

func (c *GRPCClient) ListRoles(ctx context.Context) ([]string, error)

func (*GRPCClient) ListSchemaSets 

func (c *GRPCClient) ListSchemaSets(ctx context.Context) ([]string, error)

func (*GRPCClient) Read 

func (c *GRPCClient) Read(ctx context.Context, filter *llv1.RelationTupleFilter) ([]*llv1.RelationTuple, error)

func (*GRPCClient) ReadSchema 

func (c *GRPCClient) ReadSchema(ctx context.Context) (string, error)

func (*GRPCClient) ReadSchemaSet 

func (c *GRPCClient) ReadSchemaSet(ctx context.Context, name string) (string, error)

func (*GRPCClient) RevokeRole added in v0.2.0 

func (c *GRPCClient) RevokeRole(ctx context.Context, role, objectType, objectID, subjectType, subjectID string) error

func (*GRPCClient) WhoAmI 

func (c *GRPCClient) WhoAmI(ctx context.Context) (*llv1.WhoAmIResponse, error)

func (*GRPCClient) Write 

func (c *GRPCClient) Write(ctx context.Context, writes, deletes []*llv1.RelationTuple) error

func (*GRPCClient) WriteSchema 

func (c *GRPCClient) WriteSchema(ctx context.Context, yamlData string) error

type Option 

type Option func(*GRPCClient)

Option configures the client.

func WithInsecure added in v0.2.0 

func WithInsecure() Option

WithInsecure disables TLS for the connection. By default, the client uses TLS for non-localhost addresses. Use this option for local development or when connecting to a server behind a TLS-terminating proxy on a trusted network.

func WithToken 

func WithToken(token string) Option

WithToken sets the authentication token for the client. The token will be sent as a Bearer token in the Authorization header.

type Path added in v0.2.0 

type Path struct {
	// Components are the objects in the path, ordered from root to leaf.
	Components []PathComponent

	// Relation is the relation that connects parent to child.
	Relation string
}

Path represents a hierarchical path of objects connected by a relation. The path syntax is: type:id>type:id>type:id#relation

Example: folder:root>folder:projects>file:doc.txt#parent

This represents a hierarchy where:

  • folder:projects has parent folder:root
  • file:doc.txt has parent folder:projects

Special characters in object IDs should be URL-encoded:

  • > as %3E
  • # as %23
  • : as %3A (only in the ID portion, after type)

func NewPath added in v0.2.0 

func NewPath(relation string, components ...PathComponent) *Path

NewPath creates a new Path from components and a relation.

func ParsePath added in v0.2.0 

func ParsePath(s string) (*Path, error)

ParsePath parses a path string into a Path struct.

Format: type:id>type:id>type:id#relation

Examples: 

folder:root>folder:sub>file:doc.txt#parent
org:acme>repo:backend#owner

func (*Path) Leaf added in v0.2.0 

func (p *Path) Leaf() *PathComponent

Leaf returns the last component in the path (the deepest child).

func (*Path) Root added in v0.2.0 

func (p *Path) Root() *PathComponent

Root returns the first component in the path (the topmost parent).

func (*Path) String added in v0.2.0 

func (p *Path) String() string

String returns the path as a string.

func (*Path) Tuples added in v0.2.0 

func (p *Path) Tuples() []*llv1.RelationTuple

Tuples returns the relation tuples that establish this path. Each tuple connects a child to its parent using the path's relation.

For path folder:root>folder:sub>file:doc#parent, returns:

  • folder:sub#parent@folder:root
  • file:doc#parent@folder:sub

type PathBuilder added in v0.2.0 

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

PathBuilder provides a fluent API for building paths.

func BuildPath added in v0.2.0 

func BuildPath(objType, objID string) *PathBuilder

BuildPath starts building a new path with the root object.

func (*PathBuilder) Child added in v0.2.0 

func (b *PathBuilder) Child(objType, objID string) *PathBuilder

Child adds a child component to the path.

func (*PathBuilder) Relation added in v0.2.0 

func (b *PathBuilder) Relation(relation string) *Path

Relation sets the relation that connects components and returns the built Path.

type PathComponent added in v0.2.0 

type PathComponent struct {
	Type string
	ID   string
}

PathComponent represents a single object in a path.

type RESTClient added in v0.2.0 

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

RESTClient implements Client using HTTP/REST.

func (*RESTClient) Check added in v0.2.0 

func (c *RESTClient) Check(ctx context.Context, t *llv1.RelationTuple) (bool, error)

func (*RESTClient) CheckPath added in v0.2.0 

func (c *RESTClient) CheckPath(ctx context.Context, pathStr string) (*llv1.CheckPathResponse, error)

func (*RESTClient) Close added in v0.2.0 

func (c *RESTClient) Close() error

func (*RESTClient) Delete added in v0.2.0 

func (c *RESTClient) Delete(ctx context.Context, filter *llv1.RelationTupleFilter) error

func (*RESTClient) DeleteSchemaSet added in v0.2.0 

func (c *RESTClient) DeleteSchemaSet(ctx context.Context, name string) error

func (*RESTClient) EnsurePath added in v0.2.0 

func (c *RESTClient) EnsurePath(ctx context.Context, pathStr string) error

func (*RESTClient) Expand added in v0.2.0 

func (c *RESTClient) Expand(ctx context.Context, objectType, objectID, permission string) (*llv1.ExpandTree, error)

func (*RESTClient) GrantRole added in v0.2.0 

func (c *RESTClient) GrantRole(ctx context.Context, role, objectType, objectID, subjectType, subjectID string) (*llv1.RoleAssignment, error)

func (*RESTClient) ListObjects added in v0.2.0 

func (c *RESTClient) ListObjects(ctx context.Context, subjectType, subjectID, permission, objectType string) ([]string, error)

func (*RESTClient) ListRoleAssignments added in v0.2.0 

func (c *RESTClient) ListRoleAssignments(ctx context.Context, objectType, objectID, subjectType, subjectID, role string) ([]*llv1.RoleAssignment, error)

func (*RESTClient) ListRoles added in v0.2.0 

func (c *RESTClient) ListRoles(ctx context.Context) ([]string, error)

func (*RESTClient) ListSchemaSets added in v0.2.0 

func (c *RESTClient) ListSchemaSets(ctx context.Context) ([]string, error)

func (*RESTClient) Read added in v0.2.0 

func (c *RESTClient) Read(ctx context.Context, filter *llv1.RelationTupleFilter) ([]*llv1.RelationTuple, error)

func (*RESTClient) ReadSchema added in v0.2.0 

func (c *RESTClient) ReadSchema(ctx context.Context) (string, error)

func (*RESTClient) ReadSchemaSet added in v0.2.0 

func (c *RESTClient) ReadSchemaSet(ctx context.Context, name string) (string, error)

func (*RESTClient) RevokeRole added in v0.2.0 

func (c *RESTClient) RevokeRole(ctx context.Context, role, objectType, objectID, subjectType, subjectID string) error

func (*RESTClient) WhoAmI added in v0.2.0 

func (c *RESTClient) WhoAmI(ctx context.Context) (*llv1.WhoAmIResponse, error)

func (*RESTClient) Write added in v0.2.0 

func (c *RESTClient) Write(ctx context.Context, writes, deletes []*llv1.RelationTuple) error

func (*RESTClient) WriteSchema added in v0.2.0 

func (c *RESTClient) WriteSchema(ctx context.Context, yamlData string) error

type RESTOption added in v0.2.0 

type RESTOption func(*RESTClient)

RESTOption configures the REST client.

func WithRESTInsecure added in v0.2.0 

func WithRESTInsecure() RESTOption

WithRESTInsecure forces HTTP instead of HTTPS for non-localhost addresses.

func WithRESTToken added in v0.2.0 

func WithRESTToken(token string) RESTOption

WithRESTToken sets the authentication token for the REST client.

Source Files

View all Source files

Directories

Path Synopsis
api
carabiner/ll/v1
cmd
llctl command
internal
cmd

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.