ATC Router library for Kong.

• Name
• Semantics
• APIs
  • resty.router.schema
    • new
    • add_field
    • get_field_type
  • resty.router.router
    • new
    • add_matcher
    • remove_matcher
    • execute
    • get_fields
  • resty.router.context
    • new
    • add_value
    • get_result
• Copyright and license

At the core of the library, ATC Router is a DSL that supports simple predicate and logical combinations between the predicates.

Each data referred in the DSL has a type, the type can be one of the following:

• "String" - a UTF-8 string value
• IpCidr - an IP address range in CIDR format
• IpAddr - a single IP address that can be checked against an IpCidr
• Int - an 64-bit signed integer

syntax: s = schema.new()

context: any

Create a new schema instance that can later be used by router and context.

Back to TOC

syntax: res, err = s:add_field(field, field_type)

context: any

Adds the field named field into the schema. Type can be one of the ones mentioned in the Semantics section above.

If an error occurred, nil and a string describing the error will be returned.

Back to TOC

syntax: typ, err = s:get_field_type(field)

context: any

Gets the field type from the schema.

If an error occurred, nil and a string describing the error will be returned.

Back to TOC

syntax: r = router.new(schema)

context: any

Create a new router instance that can later be used for performing matches. schema must refer to an existing schema instance.

Back to TOC

syntax: res, err = r:add_matcher(priority, uuid, atc)

context: any

Add a matcher to the router. priority is a 64-bit unsigned integer that instructs the priority for which the matchers should be evaluated. uuid is the string representation of the UUID of the matcher which will be used later for match results. atc is the matcher written in ATC DSL syntax.

If an error occurred or the matcher has syntax/semantics errors, nil and a string describing the error will be returned.

Back to TOC

syntax: res, err = r:remove_matcher(uuid)

context: any

Remove matcher with uuid from the router.

Returns true if the matcher has successfully been removed. false if the matcher does not exist.

Back to TOC

syntax: res, err = r:execute(context)

context: any

Executes the router against value provided inside the context instance.

context must use the same schema as the router, otherwise Lua error will be thrown.

Returns true if at least one matcher produced a valid match. false if the none of the matcher matched.

Back to TOC

syntax: res, err = r:get_fields()

context: any

Returns the currently used field names by all matchers inside the router as an Lua array. It can help reduce unnecessarily producing values that are not actually used by the user supplied matchers.

Back to TOC

syntax: c = context.new(schema)

context: any

Create a new context instance that can later be used for storing contextual information. for router matches. schema must refer to an existing schema instance.

Back to TOC

syntax: res, err = c:add_value(field, value)

context: any

Provides value for field inside the context.

Returns true if field exists and value has successfully been provided.

If an error occurred, nil and a string describing the error will be returned.

Back to TOC

syntax: uuid, matched_value, captures = c:get_result(matched_field)

context: any

After a successful router match, gets the match result from the context.

If matched_field is provided, then matched_value will be returned with the value matched by the specified field. If matched_field is nil or field did not match, then nil is returned for matched_value.

If the context did not contain a valid match result, nil is returned.

Otherwise, the string UUID, value matching field matched_field and regex captures from the matched route are returned.

Back to TOC

Copyright (c) 2022 Kong, Inc.

Licensed under the Apache License, Version 2.0 <LICENSE or https://www.apache.org/licenses/LICENSE-2.0>. Files in the project may not be copied, modified, or distributed except according to those terms.

Back to TOC