crossplane

README

nginx-go-crossplane

A Go port of the NGINX config/JSON converter crossplane.

Parse

This is an example that takes a path to an NGINX config file, converts it to JSON, and prints the result to stdout.

package main

import (
	"encoding/json"
	"fmt"
	"os"

	"github.com/nginxinc/nginx-go-crossplane"
)

func main() {
	path := os.Args[1]

	payload, err := crossplane.Parse(path, &crossplane.ParseOptions{})
	if err != nil {
		panic(err)
	}

	b, err := json.Marshal(payload)
	if err != nil {
		panic(err)
	}

	fmt.Println(string(b))
}

Build

This is an example that takes a path to a JSON file, converts it to an NGINX config, and prints the result to stdout.

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io/ioutil"
	"os"

	"github.com/nginxinc/nginx-go-crossplane"
)

func main() {
	path := os.Args[1]

	file, err := os.Open(path)
	if err != nil {
		panic(err)
	}

	content, err := ioutil.ReadAll(file)
	if err != nil {
		panic(err)
	}

	var payload crossplane.Payload
	if err = json.Unmarshal(content, &payload); err != nil {
		panic(err)
	}

	var buf bytes.Buffer
	if err = crossplane.Build(&buf, payload.Config[0], &crossplane.BuildOptions{}); err != nil {
		panic(err)
	}

	fmt.Println(buf.String())
}

Contributing

If you'd like to contribute to the project, please read our Contributing guide.

License

Apache License, Version 2.0

© F5 Networks, Inc. 2022

Documentation

Index

• Constants
• Variables
• func Build(w io.Writer, config Config, options *BuildOptions) error
• func BuildFiles(payload Payload, dir string, options *BuildOptions) error
• func BuildInto(payload *Payload, into Creator, options *BuildOptions) error
• func Enquote(arg string) string
• func Lex(reader io.Reader) chan NgxToken
• func SetTokenChanCap(size int)
• type BuildOptions
• type Config
• type ConfigError
• type Creator
• type Directive
  • func (d *Directive) Equal(a *Directive) bool
  • func (d Directive) IsBlock() bool
  • func (d Directive) IsComment() bool
  • func (d Directive) IsInclude() bool
  • func (d *Directive) String() string
• type Directives
• type FileString
  • func (fs *FileString) Close() error
  • func (fs *FileString) String() string
  • func (fs *FileString) Write(b []byte) (int, error)
• type NgxToken
• type ParseError
  • func (e *ParseError) Error() string
  • func (e *ParseError) MarshalJSON() ([]byte, error)
  • func (e *ParseError) Unwrap() error
• type ParseOptions
• type Payload
  • func Parse(filename string, options *ParseOptions) (*Payload, error)
  • func (p *Payload) Combined() (*Payload, error)
• type PayloadError
• type StringsCreator
  • func (sc *StringsCreator) Create(file string) (io.WriteCloser, error)
  • func (sc *StringsCreator) Reset()

Constants

const MaxIndent = 100

const TokenChanCap = 2048

Variables

var (
	ErrPrematureLexEnd = errors.New("premature end of file")
)

Functions

func Build

func Build(w io.Writer, config Config, options *BuildOptions) error

Build creates an NGINX config from a crossplane.Config.

func BuildFiles

func BuildFiles(payload Payload, dir string, options *BuildOptions) error

BuildFiles builds all of the config files in a crossplane.Payload and writes them to disk.

func BuildInto

func BuildInto(payload *Payload, into Creator, options *BuildOptions) error

BuildInto builds all of the config files in a crossplane.Payload and writes them to the Creator.

func Enquote

func Enquote(arg string) string

func Lex

func Lex(reader io.Reader) chan NgxToken

func SetTokenChanCap

func SetTokenChanCap(size int)

note: this is only used during tests, should not be changed

Types

type BuildOptions

type BuildOptions struct {
	Indent int
	Tabs   bool
	Header bool
}

type Config

type Config struct {
	File   string        `json:"file"`
	Status string        `json:"status"`
	Errors []ConfigError `json:"errors"`
	Parsed Directives    `json:"parsed"`
}

type ConfigError

type ConfigError struct {
	Line  *int  `json:"line"`
	Error error `json:"error"`
}

type Creator

type Creator interface {
	Create(string) (io.WriteCloser, error)
	Reset()
}

Creator abstracts file creation (to write configs to something other than files).

type Directive

type Directive struct {
	Directive string     `json:"directive"`
	Line      int        `json:"line"`
	Args      []string   `json:"args"`
	File      string     `json:"file,omitempty"`
	Includes  []int      `json:"includes,omitempty"`
	Block     Directives `json:"block,omitempty"`
	Comment   *string    `json:"comment,omitempty"`
}

func (*Directive) Equal

func (d *Directive) Equal(a *Directive) bool

Equal returns true if both blocks are functionally equivalent.

func (Directive) IsBlock

func (d Directive) IsBlock() bool

IsBlock returns true if this is a block directive.

func (Directive) IsComment

func (d Directive) IsComment() bool

IsComment returns true iff the directive represents a comment.

func (Directive) IsInclude

func (d Directive) IsInclude() bool

IsInclude returns true if this is an include directive.

func (*Directive) String

func (d *Directive) String() string

String makes this a Stringer, returning a string representation of the Directive. The string representation is a peak at the content of the Directive, does not represent a valid config rendering of the Directive in question.

type Directives

type Directives []*Directive

type FileString

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

FileString is a string representation of a file.

func (*FileString) Close

func (fs *FileString) Close() error

Close makes this an io.Closer.

func (*FileString) String

func (fs *FileString) String() string

String makes this a Stringer.

func (*FileString) Write

func (fs *FileString) Write(b []byte) (int, error)

Write makes this an io.Writer.

type NgxToken

type NgxToken struct {
	Value    string
	Line     int
	IsQuoted bool
	Error    error
}

type ParseError

type ParseError struct {
	What string
	File *string
	Line *int
	// Raw directive statement causing the parse error.
	Statement string
	// Block in which parse error occurred.
	BlockCtx string
	// contains filtered or unexported fields
}

func (*ParseError) Error

func (e *ParseError) Error() string

func (*ParseError) MarshalJSON

func (e *ParseError) MarshalJSON() ([]byte, error)

func (*ParseError) Unwrap

func (e *ParseError) Unwrap() error

type ParseOptions

type ParseOptions struct {
	// An array of directives to skip over and not include in the payload.
	IgnoreDirectives []string

	// If an error is found while parsing, it will be passed to this callback
	// function. The results of the callback function will be set in the
	// PayloadError struct that's added to the Payload struct's Errors array.
	ErrorCallback func(error) interface{}

	// If specified, use this alternative to open config files
	Open func(path string) (io.Reader, error)

	// Glob will return a matching list of files if specified
	Glob func(path string) ([]string, error)

	// If true, parsing will stop immediately if an error is found.
	StopParsingOnError bool

	// If true, include directives are used to combine all of the Payload's
	// Config structs into one.
	CombineConfigs bool

	// If true, only the config file with the given filename will be parsed
	// and Parse will not parse files included files.
	SingleFile bool

	// If true, comments will be parsed and added to the resulting Payload.
	ParseComments bool

	// If true, add an error to the payload when encountering a directive that
	// is unrecognized. The unrecognized directive will not be included in the
	// resulting Payload.
	ErrorOnUnknownDirectives bool

	// If true, checks that directives are in valid contexts.
	SkipDirectiveContextCheck bool

	// If true, checks that directives have a valid number of arguments.
	SkipDirectiveArgsCheck bool
}

ParseOptions determine the behavior of an NGINX config parse.

type Payload

type Payload struct {
	Status string         `json:"status"`
	Errors []PayloadError `json:"errors"`
	Config []Config       `json:"config"`
}

func Parse

func Parse(filename string, options *ParseOptions) (*Payload, error)

Parse parses an NGINX configuration file.

func (*Payload) Combined

func (p *Payload) Combined() (*Payload, error)

Combined returns a new Payload that is the same except that the inluding logic is performed on its configs. This means that the resulting Payload will always have 0 or 1 configs in its Config field.

type PayloadError

type PayloadError struct {
	File     string      `json:"file"`
	Line     *int        `json:"line"`
	Error    error       `json:"error"`
	Callback interface{} `json:"callback,omitempty"`
}

type StringsCreator

type StringsCreator struct {
	Files []*FileString
}

StringsCreator is an option for rendering config files to strings(s).

func (*StringsCreator) Create

func (sc *StringsCreator) Create(file string) (io.WriteCloser, error)

Create makes this a Creator.

func (*StringsCreator) Reset

func (sc *StringsCreator) Reset()

Reset returns the Creator to its initial state.