aip

Documentation

Overview

Package aip contains utilities used to comply with API Improvement Proposals (AIPs) from https://google.aip.dev/. This includes an AIP-160 filter parser and SQL generator and AIP-132 order by clause parser and SQL generator.

Index

• type Column
• type ColumnBuilder
  • func NewColumn() *ColumnBuilder
  • func (c *ColumnBuilder) Array() *ColumnBuilder
  • func (c *ColumnBuilder) Bool() *ColumnBuilder
  • func (c *ColumnBuilder) Build() *Column
  • func (c *ColumnBuilder) Filterable() *ColumnBuilder
  • func (c *ColumnBuilder) FilterableImplicitly() *ColumnBuilder
  • func (c *ColumnBuilder) KeyValue() *ColumnBuilder
  • func (c *ColumnBuilder) Sortable() *ColumnBuilder
  • func (c *ColumnBuilder) WithArgumentSubstitutor(f func(sub string) string) *ColumnBuilder
  • func (c *ColumnBuilder) WithDatabaseName(name string) *ColumnBuilder
  • func (c *ColumnBuilder) WithFieldPath(segments ...string) *ColumnBuilder
• type ColumnType
  • func (t ColumnType) String() string
• type FieldPath
  • func NewFieldPath(segments ...string) FieldPath
  • func (f FieldPath) Equals(other FieldPath) bool
  • func (f FieldPath) String() string
• type OrderBy
  • func MergeWithDefaultOrder(defaultOrder []OrderBy, order []OrderBy) []OrderBy
  • func ParseOrderBy(text string) ([]OrderBy, error)
• type QueryParameter
• type Table
  • func (t *Table) FilterableColumnByFieldPath(path FieldPath) (*Column, error)
  • func (t *Table) OrderByClause(order []OrderBy) (string, error)
  • func (t *Table) SortableColumnByFieldPath(path FieldPath) (*Column, error)
  • func (t *Table) WhereClause(filter *aip160.Filter, parameterPrefix string) (string, []QueryParameter, error)
• type TableBuilder
  • func NewTable() *TableBuilder
  • func (t *TableBuilder) Build() *Table
  • func (t *TableBuilder) WithColumns(columns ...*Column) *TableBuilder

Types

type Column

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

Column represents the schema of a Database column.

type ColumnBuilder

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

func NewColumn

func NewColumn() *ColumnBuilder

NewColumn starts building a new column.

func (*ColumnBuilder) Array

func (c *ColumnBuilder) Array() *ColumnBuilder

Array specifies this column is an array. The value can be queried with ':'. The operator matches if any element of the array matches. Example query: column:value

func (*ColumnBuilder) Bool

func (c *ColumnBuilder) Bool() *ColumnBuilder

Bool specifies this column has bool type in the database.

func (*ColumnBuilder) Build

func (c *ColumnBuilder) Build() *Column

Build returns the built column.

func (*ColumnBuilder) Filterable

func (c *ColumnBuilder) Filterable() *ColumnBuilder

Filterable specifies this column can be filtered on.

func (*ColumnBuilder) FilterableImplicitly

func (c *ColumnBuilder) FilterableImplicitly() *ColumnBuilder

FilterableImplicitly specifies this column can be filtered on implicitly. This means that AIP-160 filter expressions not referencing any particular field will try to search in this column.

func (*ColumnBuilder) KeyValue

func (c *ColumnBuilder) KeyValue() *ColumnBuilder

KeyValue specifies this column is an array of structs with two string members: key and value. The key is exposed as a field on the column name, the value can be queried with :, = and != Example query: tag.key=value

func (*ColumnBuilder) Sortable

func (c *ColumnBuilder) Sortable() *ColumnBuilder

Sortable specifies this column can be sorted on.

func (*ColumnBuilder) WithArgumentSubstitutor

func (c *ColumnBuilder) WithArgumentSubstitutor(f func(sub string) string) *ColumnBuilder

WithArgumentSubstitutor specifies a substitution that should happen to the user-specified filter argument before it is matched against the database value. If this option is enabled, the filter operators permitted will be limited to = (equals) and != (not equals).

func (*ColumnBuilder) WithDatabaseName

func (c *ColumnBuilder) WithDatabaseName(name string) *ColumnBuilder

WithDatabaseName specifies the database name of the column. Important: Only pass safe values (e.g. compile-time constants) to this field. User input MUST NOT flow to this field, as it will be used directly in SQL statements and would allow the user to perform SQL injection attacks.

func (*ColumnBuilder) WithFieldPath

func (c *ColumnBuilder) WithFieldPath(segments ...string) *ColumnBuilder

WithFieldPath specifies the field path the column maps to in the returned resource. Field paths are described in AIP-161.

For convenience, the field path is described here as a set of segments where each segment is joined by the traversal operator (.). E.g. the field path "metrics.`some-metric`.value" would be specified as ["metrics", "some-metric", "value"].

type ColumnType

type ColumnType int32

ColumnType is an enum for the type of a column. Valid values are in the const block above.

const (
	// ColumnTypeString is a column of type string.
	ColumnTypeString ColumnType = iota
	// ColumnTypeBool is a column of type boolean.  NULL values are mapped to FALSE.
	ColumnTypeBool = iota
)

func (ColumnType) String

func (t ColumnType) String() string

type FieldPath

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

FieldPath represents the path to a field in a message.

For example, for the given message:

message MyThing {
   message Bar {
       string foobar = 2;
   }
   string foo = 1;
   Bar bar = 2;
   map<string, Bar> named_bars = 3;
}

Some valid paths would be: foo, bar.foobar and named_bars.`bar-key`.foobar.

func NewFieldPath

func NewFieldPath(segments ...string) FieldPath

NewFieldPath initialises a new field path with the given segments.

func (FieldPath) Equals

func (f FieldPath) Equals(other FieldPath) bool

Equals returns iff two field paths refer to exactly the same field.

func (FieldPath) String

func (f FieldPath) String() string

String returns a canoncial representation of the field path, following AIP-132 / AIP-161 syntax.

type OrderBy

type OrderBy struct {
	// The field path. This is the path of the field in the
	// resource message that the AIP-132 List RPC is listing.
	FieldPath FieldPath
	// Whether the field should be sorted in descending order.
	Descending bool
}

OrderBy represents a part of an AIP-132 order_by clause.

func MergeWithDefaultOrder

func MergeWithDefaultOrder(defaultOrder []OrderBy, order []OrderBy) []OrderBy

MergeWithDefaultOrder merges the specified order with the given defaultOrder. The merge occurs as follows:

• Ordering specified in `order` takes precedence.
• For columns not specified in the `order` that appear in `defaultOrder`, ordering is applied in the order they apply in defaultOrder.

func ParseOrderBy

func ParseOrderBy(text string) ([]OrderBy, error)

ParseOrderBy parses an AIP-132 order_by list. The method validates the syntax is correct and each identifier appears at most once, but it does not validate the identifiers themselves are valid.

type QueryParameter

type QueryParameter struct {
	Name  string
	Value string
}

QueryParameter represents a query parameter.

type Table

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

Table represents the schema of a Database table, view or query.

func (*Table) FilterableColumnByFieldPath

func (t *Table) FilterableColumnByFieldPath(path FieldPath) (*Column, error)

FilterableColumnByFieldPath returns the database name of the filterable column with the given field path.

func (*Table) OrderByClause

func (t *Table) OrderByClause(order []OrderBy) (string, error)

OrderByClause returns a Standard SQL Order by clause, including "ORDER BY" and trailing new line (if an order is specified). If no order is specified, returns "".

The returned order clause is safe against SQL injection; only strings appearing from Table appear in the output.

func (*Table) SortableColumnByFieldPath

func (t *Table) SortableColumnByFieldPath(path FieldPath) (*Column, error)

SortableColumnByFieldPath returns the sortable database column with the given externally-visible field path.

func (*Table) WhereClause

func (t *Table) WhereClause(filter *aip160.Filter, parameterPrefix string) (string, []QueryParameter, error)

WhereClause creates a Standard SQL WHERE clause fragment for the given filter.

The fragment will be enclosed in parentheses and does not include the "WHERE" keyword. For example: (column LIKE @param1) Also returns the query parameters which need to be given to the database.

All field names are replaced with the safe database column names from the specified table. All user input strings are passed via query parameters, so the returned query is SQL injection safe.

type TableBuilder

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

func NewTable

func NewTable() *TableBuilder

NewTable starts building a new table.

func (*TableBuilder) Build

func (t *TableBuilder) Build() *Table

Build returns the built table.

func (*TableBuilder) WithColumns

func (t *TableBuilder) WithColumns(columns ...*Column) *TableBuilder

WithColumns specifies the columns in the table.