vintage

README

vintage

vintage is a Fastly VCL runtime in a Edge. This project provides runtime and transformer, vintage transpiles your VCLs into executable code on the edge (e.g Fastly Compute).

This project is subset of falco, which is VCL linter and interpreter. falco also includes this project to transpile VCLs inside that tool, then vintage provides the runtimes on execution. Before the transpilation, vintage checks your VCLs by falco linter so you need to have a valid VCLs on the falco.

CLI

Donwload cli command from release page and place it at your $PATH. Example of transpilation is the following:

vintage transpile --target compute --package main --output vintage.go

Describe CLI option:

option name	required	default	description
-t, --target	no	compute (Fastly Compute)	Transpile target of edge platform
-p, --package	no	main	Go package name of transpiled program
-o, --output	no	./vintage.go	Output filename (should have .go extention)

Supported Runtimes

Supprted runtimes, which can specify on -t, --target cli option are following:

• compute (default) : Fastly Compute Runtime, the generated code could run in Compute@Edge
• native : Generates raw Golang code, could run in common platforms that Golang can compile to

Run Application With Generated Code

After transpilation succeeded, you can get single go file that at --output cli option. The generated file exposes VclHandler function that implements server handler corresponds to target platform. For example, fsthttp.Handler for Fastly Compute or http.Handler for native.

To work application correctly, you need to do following steps:

1. The generated code has some dependecies so needs to run go mod tidy to install dependencies
2. If you transpiled for Fastly Compute, need to set up fastly.toml for Golang. see documentation in detail
3. You need to implement a little to start server. Fastly compute example is the following:

package main

import (
	"github.com/fastly/compute-sdk-go/fsthttp"
)

func main() {
	fsthttp.Serve(VclHandler())
}

On native:

package main

import (
	"net/http"
)

func main() {
    http.Handle("/", VclHandler())
    http.ListenAndServe(":8888", nil)
}

It's very tiny implementation! The handle has common Golang HTTP handler interface, of course you can combinate with HTTP middlewares, your favorite HTTP framework.

Note that on Fastly Compute Runtime, some packages are limited to use so ensure your framework or library can use in Compute Runtime.

Welcome Your Feedback!

We tested many kind of VCLs (production use, massive lines and include modules), they could work fine but it's not enough. If you can try vintage in your VCLs and found any problems or weired behavior, we welcome your feedback on an issue.

Contribution

• Fork this repository
• Customize / Fix problem
• Send PR :-)
• Or feel free to create issues for us. We'll look into it

License

MIT License

Contributors

• @ysugimoto

Documentation

Index

• Constants
• Variables
• func GenerateXid() string
• func ToBool[T Primitive](v T) bool
• func ToString[T Primitive](v T) string
• type Acl
  • func NewAcl(name string, opts ...AclOption) *Acl
  • func (a *Acl) Match(ip net.IP) bool
• type AclOption
  • func AclEntry(cidr string, inverse bool) AclOption
• type Backend
  • func NewBackend(name string, opts ...BackendOption) *Backend
  • func NewDirector(name string, dType DirectorType, opts ...DirectorOption) *Backend
  • func (b *Backend) Backend(ident RequestIdentity) string
• type BackendOption
  • func BackendAlwaysUseHostHeader(v bool) BackendOption
  • func BackendBetweenBytesTimeout(t time.Duration) BackendOption
  • func BackendConnectTimeout(t time.Duration) BackendOption
  • func BackendDefault() BackendOption
  • func BackendFirstByteTimeout(t time.Duration) BackendOption
  • func BackendHost(host string) BackendOption
  • func BackendPort(port string) BackendOption
  • func BackendSSL(ssl bool) BackendOption
• type Director
  • func (d *Director) Backend(ident RequestIdentity) string
• type DirectorOption
  • func DirectorBackend(opts ...DirectorOption) DirectorOption
  • func DirectorProperty(key string, value any) DirectorOption
• type DirectorType
• type Logger
• type LoggerInitiator
• type LoggingEndpoint
  • func NewLoggingEndpoint(name string, initiator LoggerInitiator) *LoggingEndpoint
  • func (l *LoggingEndpoint) Write(message string) error
• type Primitive
• type RawHeader
• type RegexpMatchedGroup
  • func RegexpMatch(pattern, subject string) (bool, RegexpMatchedGroup, error)
  • func (re RegexpMatchedGroup) At(index int) string
• type RequestIdentity
• type State
  • func Error(err error) (State, error)
• type Table
  • func NewTable(name, itemType string, items ...TableOption) *Table
  • func (t *Table) IsEdgeDictionary() bool
• type TableOption
  • func EdgeDictionary() TableOption
  • func TableItem(name string, value any) TableOption

Constants

const (
	Millisecond time.Duration = time.Millisecond
	Second      time.Duration = time.Second
	Minute      time.Duration = time.Minute
	Hour        time.Duration = time.Hour
	Day         time.Duration = 24 * time.Hour
	Year        time.Duration = 24 * 365 * time.Hour
)

Alias of time.Duration for VCL RTIME value

Variables

var LocalHost = net.IPv4(127, 0, 0, 1)

Temporal value of local IP

Functions

func GenerateXid

func GenerateXid() string

func ToBool

func ToBool[T Primitive](v T) bool

func ToString

func ToString[T Primitive](v T) string

Types

type Acl

type Acl struct {
	Name  string
	CIDRs []struct {
		IpNet   *net.IPNet
		Inverse bool
	}
}

func NewAcl

func NewAcl(name string, opts ...AclOption) *Acl

func (*Acl) Match

func (a *Acl) Match(ip net.IP) bool

type AclOption

type AclOption func(a *Acl)

func AclEntry

func AclEntry(cidr string, inverse bool) AclOption

type Backend

type Backend struct {
	Name                string
	IsDefault           bool
	Port                string
	Host                string
	SSL                 bool
	AlwaysUseHostHeader bool
	ConnectTimeout      time.Duration
	FirstByteTimeout    time.Duration
	BetweenBytesTimeout time.Duration
	Director            *Director
}

func NewBackend

func NewBackend(name string, opts ...BackendOption) *Backend

func NewDirector

func NewDirector(name string, dType DirectorType, opts ...DirectorOption) *Backend

func (*Backend) Backend

func (b *Backend) Backend(ident RequestIdentity) string

type BackendOption

type BackendOption func(b *Backend)

func BackendAlwaysUseHostHeader

func BackendAlwaysUseHostHeader(v bool) BackendOption

func BackendBetweenBytesTimeout

func BackendBetweenBytesTimeout(t time.Duration) BackendOption

func BackendConnectTimeout

func BackendConnectTimeout(t time.Duration) BackendOption

func BackendDefault

func BackendDefault() BackendOption

func BackendFirstByteTimeout

func BackendFirstByteTimeout(t time.Duration) BackendOption

func BackendHost

func BackendHost(host string) BackendOption

func BackendPort

func BackendPort(port string) BackendOption

func BackendSSL

func BackendSSL(ssl bool) BackendOption

type Director

type Director struct {
	Type       DirectorType
	Properties map[string]any
	Backends   []map[string]any
	// contains filtered or unexported fields
}

func (*Director) Backend

func (d *Director) Backend(ident RequestIdentity) string

type DirectorOption

type DirectorOption func(d *Director)

func DirectorBackend

func DirectorBackend(opts ...DirectorOption) DirectorOption

func DirectorProperty

func DirectorProperty(key string, value any) DirectorOption

type DirectorType

type DirectorType string

const (
	Random   DirectorType = "random"
	Fallback DirectorType = "fallback"
	Hash     DirectorType = "hash"
	Client   DirectorType = "client"
	CHash    DirectorType = "chash"
)

type Logger

type Logger interface {
	Write(message []byte) error
}

Define Logger interface to switch native logger that is provided by log package or Fastly logger that is provided by compute-sdk-go/rtlog package

type LoggerInitiator

type LoggerInitiator func(name string) (io.Writer, error)

Logger interface creator function in order to inject Logger interface from each runtimes

type LoggingEndpoint

type LoggingEndpoint struct {
	Name string
	// contains filtered or unexported fields
}

func NewLoggingEndpoint

func NewLoggingEndpoint(name string, initiator LoggerInitiator) *LoggingEndpoint

func (*LoggingEndpoint) Write

func (l *LoggingEndpoint) Write(message string) error

type Primitive

type Primitive interface {
	string | int64 | float64 | bool | net.IP | time.Duration | time.Time | *Backend | *Acl | *Table
}

type RawHeader

type RawHeader map[string][]string

RawHeader represents underlying type of http.Header. To abstract HTTP context and WASM runtime could not import net/http package, Our runtime would use as Golang underlying type

type RegexpMatchedGroup

type RegexpMatchedGroup []string

RegexpMatchedGroup represents regexp matched group values which is stored when "~" or "!~" operator is used

func RegexpMatch

func RegexpMatch(pattern, subject string) (bool, RegexpMatchedGroup, error)

RegexpMatch is function that wraps regular expression matching Returns matches result and capture groups

func (RegexpMatchedGroup) At

func (re RegexpMatchedGroup) At(index int) string

type RequestIdentity

type RequestIdentity struct {
	Hash   string // value of req.hash
	Client string // value of client.identity
}

type State

type State string

const (
	NONE          State = ""
	LOOKUP        State = "lookup"
	PASS          State = "pass"
	HASH          State = "hash"
	ERROR         State = "error"
	RESTART       State = "restart"
	DELIVER       State = "deliver"
	FETCH         State = "fetch"
	DELIVER_STALE State = "deliver_stale"
	LOG           State = "log"
)

func Error

func Error(err error) (State, error)

type Table

type Table struct {
	Name  string
	Type  string
	Items map[string]any
	// contains filtered or unexported fields
}

func NewTable

func NewTable(name, itemType string, items ...TableOption) *Table

func (*Table) IsEdgeDictionary

func (t *Table) IsEdgeDictionary() bool

type TableOption

type TableOption func(t *Table)

func EdgeDictionary

func EdgeDictionary() TableOption

func TableItem

func TableItem(name string, value any) TableOption