common

package
v0.387.1 Latest Latest
Warning

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

Go to latest
Published: Oct 28, 2024 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	// FtlUnitTypePath is the path to the FTL unit type.
	FtlUnitTypePath = "github.com/TBD54566975/ftl/go-runtime/ftl.Unit"
	// FtlOptionTypePath is the path to the FTL option type.
	FtlOptionTypePath = "github.com/TBD54566975/ftl/go-runtime/ftl.Option"
)
View Source
var DirectiveParser = participle.MustBuild[directiveWrapper](
	participle.Lexer(schema.Lexer),
	participle.Elide("Whitespace"),
	participle.Unquote(),
	participle.UseLookahead(2),
	participle.Union[Directive](&DirectiveVerb{}, &DirectiveData{}, &DirectiveEnum{}, &DirectiveTypeAlias{},
		&DirectiveIngress{}, &DirectiveCronJob{}, &DirectiveRetry{}, &DirectiveSubscriber{}, &DirectiveExport{},
		&DirectiveTypeMap{}, &DirectiveEncoding{}),
	participle.Union[schema.IngressPathComponent](&schema.IngressPathLiteral{}, &schema.IngressPathParameter{}),
)

Functions

func ApplyMetadata added in v0.292.0

func ApplyMetadata[T schema.Decl](pass *analysis.Pass, obj types.Object, apply func(md *ExtractedMetadata)) bool

ApplyMetadata applies the extracted metadata to the object, if present. Returns true if metadata was found and applied.

func CallExprFromVar added in v0.292.0

func CallExprFromVar(node *ast.GenDecl) optional.Option[*ast.CallExpr]

CallExprFromVar extracts a call expression from a variable declaration, if present.

func Deref added in v0.291.0

func Deref[T types.Object](pass *analysis.Pass, node ast.Expr) (string, T)

func Errorf

func Errorf(pass *analysis.Pass, node ast.Node, format string, args ...interface{})

func ExtractComments

func ExtractComments(doc *ast.CommentGroup) []string

ExtractComments extracts the comments from the given comment group.

func ExtractStringLiteralArg added in v0.291.0

func ExtractStringLiteralArg(pass *analysis.Pass, node *ast.CallExpr, argIndex int) string

ExtractStringLiteralArg extracts a string literal argument from a call expression at the given index.

func ExtractType

func ExtractType(pass *analysis.Pass, node ast.Node) optional.Option[schema.Type]

ExtractType extracts the schema type for the given node.

func FtlModuleFromGoPackage

func FtlModuleFromGoPackage(pkgPath string) (string, error)

FtlModuleFromGoPackage returns the FTL module name from the given Go package path.

func FuncPathEquals added in v0.292.0

func FuncPathEquals(pass *analysis.Pass, callExpr *ast.CallExpr, path string) bool

FuncPathEquals checks if the function call expression is a call to the given path.

func GetAllFacts added in v0.287.0

func GetAllFacts(pass *analysis.Pass) map[types.Object][]SchemaFactValue

func GetAllFactsExtractionStatus added in v0.287.0

func GetAllFactsExtractionStatus(pass *analysis.Pass) map[types.Object]SchemaFactValue

GetAllFactsExtractionStatus merges schema facts inclusive of all available results and the present pass facts. For a given object, it provides the current extraction status.

If multiple extraction facts are present for the same object, the facts will be prioritized by type: 1. ExtractedDecl 2. FailedExtraction 3. NeedsExtraction

All other fact types are ignored.

func GetAllFactsOfType added in v0.303.0

func GetAllFactsOfType[T SchemaFactValue](pass *analysis.Pass) map[types.Object][]T

GetAllFactsOfType returns all facts of the provided type marked on objects, across the current pass and results from prior passes. If multiple of the same fact type are marked on a single object, the first fact is returned.

func GetCurrentPassFacts added in v0.287.0

func GetCurrentPassFacts[T SchemaFactValue](pass *analysis.Pass) map[types.Object][]T

GetCurrentPassFacts returns all facts of the provided type marked on objects during the current pass. If multiple of the same fact type are marked on a single object, the first fact is returned.

func GetDeclTypeName added in v0.287.0

func GetDeclTypeName(d schema.Decl) string

GetDeclTypeName returns the name of the declaration type, e.g. "verb" for *schema.Verb.

func GetFactForObject

func GetFactForObject[T SchemaFactValue](pass *analysis.Pass, obj types.Object) optional.Option[T]

GetFactForObject returns the first fact of the provided type marked on the object.

func GetFactsForObject

func GetFactsForObject[T SchemaFactValue](pass *analysis.Pass, obj types.Object) []T

GetFactsForObject returns the all facts of the provided type marked on the object.

func GetNativeName added in v0.261.0

func GetNativeName(obj types.Object) string

GetNativeName returns the fully qualified name of the object, e.g. "github.com/TBD54566975/ftl/go-runtime/ftl.Unit".

func GetObjectForNode

func GetObjectForNode(typesInfo *types.Info, node ast.Node) optional.Option[types.Object]

GetObjectForNode returns the types.Object for the given node.

func GetTypeInfoForNode added in v0.282.0

func GetTypeInfoForNode(node ast.Node, info *types.Info) optional.Option[types.Type]

func GoPosToSchemaPos

func GoPosToSchemaPos(fset *token.FileSet, pos token.Pos) schema.Position

GoPosToSchemaPos converts a Go token.Pos to a schema.Position.

func IsExternalType added in v0.282.0

func IsExternalType(path string) bool

IsExternalType returns true if the object is from an external package.

func IsPathInModule added in v0.292.2

func IsPathInModule(pkg *types.Package, path string) bool

IsPathInModule returns true if the given path is in the module.

func IsSelfReference

func IsSelfReference(pass *analysis.Pass, obj types.Object, t schema.Type) bool

IsSelfReference returns true if the schema reference refers to this object itself.

func IsType

func IsType[T types.Type](t types.Type) bool

IsType returns true if the given type is of the specified type.

func MarkFailedExtraction

func MarkFailedExtraction(pass *analysis.Pass, obj types.Object)

MarkFailedExtraction marks the given object as having failed extraction.

func MarkFunctionCall added in v0.303.0

func MarkFunctionCall(pass *analysis.Pass, obj types.Object, callee types.Object, pos schema.Position)

MarkFunctionCall marks the given object as having an outbound function call.

func MarkIncludeNativeName added in v0.372.0

func MarkIncludeNativeName(pass *analysis.Pass, obj types.Object, node schema.Node)

MarkIncludeNativeName marks the given object as needing to be added to the native names map.

func MarkMaybeTypeEnum added in v0.287.0

func MarkMaybeTypeEnum(pass *analysis.Pass, obj types.Object, enum *schema.Enum)

MarkMaybeTypeEnum marks the given object as a possible type enum discriminator.

func MarkMaybeTypeEnumVariant added in v0.287.0

func MarkMaybeTypeEnumVariant(pass *analysis.Pass, obj types.Object, variant *schema.EnumVariant,
	parent types.Object, valueFunc func(pass *analysis.Pass) optional.Option[*schema.TypeValue])

MarkMaybeTypeEnumVariant marks the given object as a possible type enum variant.

func MarkMaybeValueEnumVariant added in v0.287.0

func MarkMaybeValueEnumVariant(pass *analysis.Pass, obj types.Object, variant *schema.EnumVariant, typ types.Object)

MarkMaybeValueEnumVariant marks the given object as a possible value enum variant.

func MarkMetadata

func MarkMetadata(pass *analysis.Pass, obj types.Object, md *ExtractedMetadata)

func MarkNeedsExtraction added in v0.287.0

func MarkNeedsExtraction(pass *analysis.Pass, obj types.Object)

MarkNeedsExtraction marks the given object as needing extraction.

func MarkSchemaDecl

func MarkSchemaDecl(pass *analysis.Pass, obj types.Object, decl schema.Decl)

MarkSchemaDecl marks the given object as having been extracted to the given schema decl.

func NewCallDeclExtractor added in v0.305.0

func NewCallDeclExtractor[T schema.Decl](name string, extractFunc ExtractCallDeclFunc[T], callPaths ...string) *analysis.Analyzer

NewCallDeclExtractor extracts declarations from call expressions, e.g. `ftl.Subscription("name")`.

func NewDeclExtractor

func NewDeclExtractor[T schema.Decl, N ast.Node](name string, extractFunc ExtractDeclFunc[T, N]) *analysis.Analyzer

NewDeclExtractor creates a new schema declaration extractor and registers its extraction function with the common extractor registry. The registry provides functions for extracting schema declarations by type and is used to extract transitive declarations in a separate pass from the decl extraction pass.

func NewExtractor

func NewExtractor(name string, factType analysis.Fact, run func(*analysis.Pass) (interface{}, error)) *analysis.Analyzer

NewExtractor creates a new schema element extractor.

func NewResourceDeclExtractor added in v0.372.0

func NewResourceDeclExtractor[T schema.Decl](name string, extractFunc ExtractResourceDeclFunc[T], typePaths ...string) *analysis.Analyzer

NewResourceDeclExtractor creates a new schema declaration extractor to extract resources, e.g. Database, Subscription, Topics.

Resources are extracted on the basis of their underlying type, e.g. ftl.PostgresDatabaseHandle, rather than an FTL directive.

func NoEndColumnErrorf

func NoEndColumnErrorf(pass *analysis.Pass, pos token.Pos, format string, args ...interface{})

func NoEndColumnWarnf added in v0.282.0

func NoEndColumnWarnf(pass *analysis.Pass, pos token.Pos, format string, args ...interface{})

func TokenErrorf

func TokenErrorf(pass *analysis.Pass, pos token.Pos, tokenText string, format string, args ...interface{})

func Wrapf

func Wrapf(pass *analysis.Pass, node ast.Node, err error, format string, args ...interface{})

Types

type DefaultFact added in v0.260.0

type DefaultFact[T any] struct {
	// contains filtered or unexported fields
}

DefaultFact should be used as the base type for all schema facts. Each Analyzer needs a uniuqe Fact type that is otherwise identical, and this type simply reduces that boilerplate.

Usage:

type Fact = common.DefaultFact[struct{}]

func (*DefaultFact[T]) AFact added in v0.260.0

func (*DefaultFact[T]) AFact()

func (*DefaultFact[T]) Add added in v0.287.0

func (t *DefaultFact[T]) Add(v SchemaFactValue)

func (*DefaultFact[T]) Get added in v0.260.0

func (t *DefaultFact[T]) Get() []SchemaFactValue

type DiagnosticCategory

type DiagnosticCategory string
const (
	Info  DiagnosticCategory = "info"
	Warn  DiagnosticCategory = "warn"
	Error DiagnosticCategory = "error"
)

func (DiagnosticCategory) ToErrorLevel

func (e DiagnosticCategory) ToErrorLevel() builderrors.ErrorLevel

type Directive

type Directive interface {
	SetPosition(pos token.Pos)
	GetPosition() token.Pos
	GetTypeName() string
	// MustAnnotate returns the AST nodes that can be annotated by this directive.
	MustAnnotate() []ast.Node
	// contains filtered or unexported methods
}

Directive is a directive in a Go FTL module, e.g. //ftl:ingress http GET /foo/bar

func ParseDirectives

func ParseDirectives(pass *analysis.Pass, node ast.Node, docs *ast.CommentGroup) []Directive

type DirectiveCronJob

type DirectiveCronJob struct {
	Pos token.Pos

	Cron cron.Pattern `parser:"'cron' @@"`
}

func (*DirectiveCronJob) GetPosition

func (d *DirectiveCronJob) GetPosition() token.Pos

func (*DirectiveCronJob) GetTypeName

func (*DirectiveCronJob) GetTypeName() string

func (*DirectiveCronJob) IsExported

func (d *DirectiveCronJob) IsExported() bool

func (*DirectiveCronJob) MustAnnotate

func (*DirectiveCronJob) MustAnnotate() []ast.Node

func (*DirectiveCronJob) SetPosition

func (d *DirectiveCronJob) SetPosition(pos token.Pos)

func (*DirectiveCronJob) String

func (d *DirectiveCronJob) String() string

type DirectiveData

type DirectiveData struct {
	Pos token.Pos

	Data   bool `parser:"@'data'"`
	Export bool `parser:"@'export'?"`
}

func (*DirectiveData) GetPosition

func (d *DirectiveData) GetPosition() token.Pos

func (*DirectiveData) GetTypeName

func (*DirectiveData) GetTypeName() string

func (*DirectiveData) IsExported

func (d *DirectiveData) IsExported() bool

func (*DirectiveData) MustAnnotate

func (*DirectiveData) MustAnnotate() []ast.Node

func (*DirectiveData) SetPosition

func (d *DirectiveData) SetPosition(pos token.Pos)

func (*DirectiveData) String

func (d *DirectiveData) String() string

type DirectiveEncoding added in v0.336.0

type DirectiveEncoding struct {
	Pos token.Pos

	Type    string `parser:"'encoding' @('json')?"`
	Lenient bool   `parser:"@'lenient'"`
}

DirectiveEncoding can be used to enable custom encoding behavior.

func (*DirectiveEncoding) GetPosition added in v0.336.0

func (d *DirectiveEncoding) GetPosition() token.Pos

func (*DirectiveEncoding) GetTypeName added in v0.336.0

func (*DirectiveEncoding) GetTypeName() string

func (*DirectiveEncoding) MustAnnotate added in v0.336.0

func (*DirectiveEncoding) MustAnnotate() []ast.Node

func (*DirectiveEncoding) SetPosition added in v0.336.0

func (d *DirectiveEncoding) SetPosition(pos token.Pos)

func (*DirectiveEncoding) String added in v0.336.0

func (d *DirectiveEncoding) String() string

type DirectiveEnum

type DirectiveEnum struct {
	Pos token.Pos

	Enum   bool `parser:"@'enum'"`
	Export bool `parser:"@'export'?"`
}

func (*DirectiveEnum) GetPosition

func (d *DirectiveEnum) GetPosition() token.Pos

func (*DirectiveEnum) GetTypeName

func (*DirectiveEnum) GetTypeName() string

func (*DirectiveEnum) IsExported

func (d *DirectiveEnum) IsExported() bool

func (*DirectiveEnum) MustAnnotate

func (*DirectiveEnum) MustAnnotate() []ast.Node

func (*DirectiveEnum) SetPosition

func (d *DirectiveEnum) SetPosition(pos token.Pos)

func (*DirectiveEnum) String

func (d *DirectiveEnum) String() string

type DirectiveExport

type DirectiveExport struct {
	Pos token.Pos

	Export bool `parser:"@'export'"`
}

DirectiveExport is used on declarations that don't include export in other directives.

func (*DirectiveExport) GetPosition

func (d *DirectiveExport) GetPosition() token.Pos

func (*DirectiveExport) GetTypeName

func (*DirectiveExport) GetTypeName() string

func (*DirectiveExport) IsExported added in v0.292.0

func (d *DirectiveExport) IsExported() bool

func (*DirectiveExport) MustAnnotate

func (*DirectiveExport) MustAnnotate() []ast.Node

func (*DirectiveExport) SetPosition

func (d *DirectiveExport) SetPosition(pos token.Pos)

func (*DirectiveExport) String

func (d *DirectiveExport) String() string

type DirectiveIngress

type DirectiveIngress struct {
	Pos token.Pos

	Type   string                        `parser:"'ingress' @('http')?"`
	Method string                        `parser:"@('GET' | 'POST' | 'PUT' | 'DELETE')"`
	Path   []schema.IngressPathComponent `parser:"('/' @@)+"`
}

func (*DirectiveIngress) GetPosition

func (d *DirectiveIngress) GetPosition() token.Pos

func (*DirectiveIngress) GetTypeName

func (*DirectiveIngress) GetTypeName() string

func (*DirectiveIngress) IsExported

func (d *DirectiveIngress) IsExported() bool

func (*DirectiveIngress) MustAnnotate

func (*DirectiveIngress) MustAnnotate() []ast.Node

func (*DirectiveIngress) SetPosition

func (d *DirectiveIngress) SetPosition(pos token.Pos)

func (*DirectiveIngress) String

func (d *DirectiveIngress) String() string

type DirectiveRetry

type DirectiveRetry struct {
	Pos token.Pos

	Count       *int    `parser:"'retry' (@Number Whitespace)?"`
	MinBackoff  string  `parser:"@(Number (?! Whitespace) Ident)?"`
	MaxBackoff  string  `parser:"@(Number (?! Whitespace) Ident)?"`
	CatchModule *string `parser:"('catch' (@Ident '.')?"`
	CatchVerb   *string `parser:"@Ident)?"`
}

func (*DirectiveRetry) Catch added in v0.325.0

func (d *DirectiveRetry) Catch() optional.Option[schema.Ref]

func (*DirectiveRetry) GetPosition

func (d *DirectiveRetry) GetPosition() token.Pos

func (*DirectiveRetry) GetTypeName

func (*DirectiveRetry) GetTypeName() string

func (*DirectiveRetry) MustAnnotate

func (*DirectiveRetry) MustAnnotate() []ast.Node

func (*DirectiveRetry) SetPosition

func (d *DirectiveRetry) SetPosition(pos token.Pos)

func (*DirectiveRetry) String

func (d *DirectiveRetry) String() string

type DirectiveSubscriber

type DirectiveSubscriber struct {
	Pos token.Pos

	Name string `parser:"'subscribe' @Ident"`
}

DirectiveSubscriber is used to subscribe a sink to a subscription

func (*DirectiveSubscriber) GetPosition

func (d *DirectiveSubscriber) GetPosition() token.Pos

func (*DirectiveSubscriber) GetTypeName

func (*DirectiveSubscriber) GetTypeName() string

func (*DirectiveSubscriber) MustAnnotate

func (*DirectiveSubscriber) MustAnnotate() []ast.Node

func (*DirectiveSubscriber) SetPosition

func (d *DirectiveSubscriber) SetPosition(pos token.Pos)

func (*DirectiveSubscriber) String

func (d *DirectiveSubscriber) String() string

type DirectiveTypeAlias

type DirectiveTypeAlias struct {
	Pos token.Pos

	TypeAlias bool `parser:"@'typealias'"`
	Export    bool `parser:"@'export'?"`
}

func (*DirectiveTypeAlias) GetPosition

func (d *DirectiveTypeAlias) GetPosition() token.Pos

func (*DirectiveTypeAlias) GetTypeName

func (*DirectiveTypeAlias) GetTypeName() string

func (*DirectiveTypeAlias) IsExported

func (d *DirectiveTypeAlias) IsExported() bool

func (*DirectiveTypeAlias) MustAnnotate

func (*DirectiveTypeAlias) MustAnnotate() []ast.Node

func (*DirectiveTypeAlias) SetPosition

func (d *DirectiveTypeAlias) SetPosition(pos token.Pos)

func (*DirectiveTypeAlias) String

func (d *DirectiveTypeAlias) String() string

type DirectiveTypeMap added in v0.282.0

type DirectiveTypeMap struct {
	Pos token.Pos

	Runtime    string `parser:"'typemap' @('go' | 'kotlin' | 'java')"`
	NativeName string `parser:"@String"`
}

DirectiveTypeMap is used to declare a native type to deserialize to in a given runtime.

func (*DirectiveTypeMap) GetPosition added in v0.282.0

func (d *DirectiveTypeMap) GetPosition() token.Pos

func (*DirectiveTypeMap) GetTypeName added in v0.282.0

func (*DirectiveTypeMap) GetTypeName() string

func (*DirectiveTypeMap) MustAnnotate added in v0.282.0

func (*DirectiveTypeMap) MustAnnotate() []ast.Node

func (*DirectiveTypeMap) SetPosition added in v0.282.0

func (d *DirectiveTypeMap) SetPosition(pos token.Pos)

func (*DirectiveTypeMap) String added in v0.282.0

func (d *DirectiveTypeMap) String() string

type DirectiveVerb

type DirectiveVerb struct {
	Pos token.Pos

	Verb   bool `parser:"@'verb'"`
	Export bool `parser:"@'export'?"`
}

func (*DirectiveVerb) GetPosition

func (d *DirectiveVerb) GetPosition() token.Pos

func (*DirectiveVerb) GetTypeName

func (*DirectiveVerb) GetTypeName() string

func (*DirectiveVerb) IsExported

func (d *DirectiveVerb) IsExported() bool

func (*DirectiveVerb) MustAnnotate

func (*DirectiveVerb) MustAnnotate() []ast.Node

func (*DirectiveVerb) SetPosition

func (d *DirectiveVerb) SetPosition(pos token.Pos)

func (*DirectiveVerb) String

func (d *DirectiveVerb) String() string

type Exportable

type Exportable interface {
	IsExported() bool
}

type ExternalType added in v0.300.0

type ExternalType struct{}

ExternalType is a fact for marking an external type.

type ExtractCallDeclFunc added in v0.305.0

type ExtractCallDeclFunc[T schema.Decl] func(pass *analysis.Pass, object types.Object, node *ast.GenDecl, callExpr *ast.CallExpr, callPath string) optional.Option[T]

ExtractCallDeclFunc extracts a schema declaration from the given node.

type ExtractDeclFunc

type ExtractDeclFunc[T schema.Decl, N ast.Node] func(pass *analysis.Pass, node N, object types.Object) optional.Option[T]

ExtractDeclFunc extracts a schema declaration from the given node.

func ExtractFuncForDecl

func ExtractFuncForDecl(t schema.Decl) (ExtractDeclFunc[schema.Decl, ast.Node], error)

ExtractFuncForDecl returns the registered extraction function for the given declaration type.

type ExtractResourceDeclFunc added in v0.372.0

type ExtractResourceDeclFunc[T schema.Decl] func(pass *analysis.Pass, object types.Object, node *ast.TypeSpec, typePath string) optional.Option[T]

ExtractResourceDeclFunc extracts a schema declaration from the given node, providing the path to the underlying resource type.

type ExtractedDecl

type ExtractedDecl struct {
	Decl schema.Decl
}

ExtractedDecl is a fact for associating an object with an extracted schema decl.

type ExtractedMetadata

type ExtractedMetadata struct {
	Type       schema.Decl
	IsExported bool
	Metadata   []schema.Metadata
	Comments   []string
}

ExtractedMetadata is a fact for associating an object with extracted schema metadata.

type ExtractorResult

type ExtractorResult struct {
	Facts []analysis.ObjectFact
}

ExtractorResult contains the results of an extraction pass.

func NewExtractorResult

func NewExtractorResult(pass *analysis.Pass) ExtractorResult

NewExtractorResult creates a new ExtractorResult with all object facts from this pass.

type FailedExtraction

type FailedExtraction struct{}

FailedExtraction is a fact for marking a type that failed to be extracted by another extractor.

type FunctionCall added in v0.303.0

type FunctionCall struct {
	// The function being called.
	Callee types.Object
	// Position where the call takes place.
	Position schema.Position
}

FunctionCall is a fact for marking an outbound function call on a function.

type IncludeNativeName added in v0.372.0

type IncludeNativeName struct {
	// The schema node associated with this native name.
	Node schema.Node
}

IncludeNativeName marks a node that needs to be added to the native names map provided in the extraction result.

type MaybeTypeEnum added in v0.287.0

type MaybeTypeEnum struct {
	Enum *schema.Enum
}

MaybeTypeEnum is a fact for marking an object as a possible type enum discriminator.

type MaybeTypeEnumVariant added in v0.287.0

type MaybeTypeEnumVariant struct {
	GetValue func(pass *analysis.Pass) optional.Option[*schema.TypeValue]
	// the parent enum
	Parent types.Object
	// this variant
	Variant *schema.EnumVariant
}

MaybeTypeEnumVariant is a fact for marking an object as a possible type enum variant.

type MaybeValueEnumVariant added in v0.287.0

type MaybeValueEnumVariant struct {
	// this variant
	Variant *schema.EnumVariant
	// type of the variant
	Type types.Object
}

MaybeValueEnumVariant is a fact for marking an object as a possible value enum variant.

type NeedsExtraction

type NeedsExtraction struct{}

NeedsExtraction is a fact for marking a type that needs to be extracted by another extractor.

type SchemaFact

type SchemaFact interface {
	analysis.Fact
	Add(v SchemaFactValue)
	Get() []SchemaFactValue
}

SchemaFact is a fact that associates a schema node with a Go object.

type SchemaFactValue

type SchemaFactValue interface {
	// contains filtered or unexported methods
}

SchemaFactValue is the value of a SchemaFact.

type VerbCall added in v0.303.0

type VerbCall struct {
	// The verb being called.
	VerbRef *schema.Ref
}

VerbCall is a fact for marking a call to an FTL verb on a function.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL