prefixgen

Documentation

Overview

Package prefixgen defines a language for generating connection prefixes. The motivating use case was to create prefixes for use in Shadowsocks clients. However, the prefix generators offered by this package are just byte string generators.

The entrypoint to this package is the New function.

Index

• Variables
• func Hex(args []string) (func() []byte, error)
• func RandomBytes(args []string) (func() []byte, error)
• func RandomInt(args []string) (func() []byte, error)
• func RandomString(args []string) (func() []byte, error)
• type PrefixGen
  • func New(generator string) (PrefixGen, error)

Variables

var Builtins = map[string]builtin{
	"hex":           Hex,
	"random_string": RandomString,
	"random_int":    RandomInt,
	"random_bytes":  RandomBytes,
}

Builtins is a collection of built-in functions which can be referenced in the generator provided to New.

Functions

func Hex

func Hex(args []string) (func() []byte, error)

Hex is a builtin function (see New and Builtins).

Args:

0 (hex input): string
	even in length, containing only characters in [0-9A-Fa-f]

Parses argument 0 into raw bytes and prints to the output.

Example:

$hex(BEEFFACE33)

func RandomBytes

func RandomBytes(args []string) (func() []byte, error)

RandomBytes is a builtin function (see New and Builtins).

Args:

0 (min length): integer
1 (max length): integer
2 (byte set): string, optional
	even in length, containing only characters in [0-9A-Fa-f]
	each group of two characters represents a possible choice

Produces a byte string, whose length will be [min length, max length). If a byte set is provided, only the specified bytes will be considered. The default byte set is all possible bytes.

Examples:

$random_bytes(1, 10)
$random_bytes(1, 10, 010203A1A2A3)

func RandomInt

func RandomInt(args []string) (func() []byte, error)

RandomInt is a builtin function (see New and Builtins).

Args:

0 (min): integer
1 (max): integer

Produces an integer in the range [min, max).

Examples:

$random_int(0, 10)
$random_int(-1000, 1000)

func RandomString

func RandomString(args []string) (func() []byte, error)

RandomString is a builtin function (see New and Builtins).

Args:

0 (min length): integer
1 (max length): integer
2 (character set): string, optional

Produces a string, whose length will be [min length, max length). If a character set is provided, only the specified characters will be considered. The default character set is the set of 26 alphabetic characters, lower and upper case.

Examples:

$random_string(1, 10)
$random_string(1, 10, aeiou)

Types

type PrefixGen

type PrefixGen func() []byte

PrefixGen is used to produces connection prefixes. This is a generator compiled to a Go function See the New function.

func New

func New(generator string) (PrefixGen, error)

New creates a new PrefixGen based on a generator. The generator is a rudimentary program, with a grammar defined in EBNF as:

letter = "A" | "B" | "C" | "D" | "E" | "F" | "G"
  | "H" | "I" | "J" | "K" | "L" | "M" | "N"
  | "O" | "P" | "Q" | "R" | "S" | "T" | "U"
  | "V" | "W" | "X" | "Y" | "Z" | "a" | "b"
  | "c" | "d" | "e" | "f" | "g" | "h" | "i"
  | "j" | "k" | "l" | "m" | "n" | "o" | "p"
  | "q" | "r" | "s" | "t" | "u" | "v" | "w"
  | "x" | "y" | "z" ;
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
whitespace = " " | "\t" | "\n" | "\r" ;
char = letter | digit | whitespace

number = digit, { digit } ;
string = char, { char } ;
identifier = letter, { letter | "_" } ;

version = "v", number , ".", number ;
arg list = string, { ",", " ", string } ;
function call = "$", identifier, "(", [ arg list ], ")" ;

generator = version, " ", { string | whitespace | function call }

where the function calls reference a limited set of built-in functions defined in Builtins. Nested function calls are not supported.

Generators begin with a version specifier. This specifier is used to make parsing decisions, but is left out of the output prefix.

Example generators:

httpGet = `v1.0 GET /$random_string(5, 10) HTTP/1.1`

dnsOverTCP = `v1.0 $hex(05DC)$random_bytes(2, 3)$hex(0120)`