Using AS3 Ninja

Run AS3 Ninja with Docker

Starting an ephemeral/temporary container for use of the API:

docker run -it --rm -p 8000:8000 simonkowallik/as3ninja
_images/_docker_ephemeral.svg

Creating a persistent container for CLI and API usage:

docker container create --name as3ninja -p 8000:8000 simonkowallik/as3ninja

# start the as3ninja container in background
docker start -a as3ninja
_images/_docker_persistent.svg

Important

The AS3 Schema files need to be downloaded from github.com to validate AS3 Declarations. AS3 Ninja as3ninja.AS3Schema.updateschemas() is doing that for you automatically, but the Docker Container will need access to https://github.com.

Using the CLI with Docker

Docker can be used to run the command line.

$ tree ./examples/simple/
./examples/simple/
├── http_path_header.iRule
├── ninja.yaml
├── sorry_page.iRule
└── template.j2

This example assumes the relevant Template Configurations and Declaration Templates are stored in ./examples/simple.

1as3ninja:
2  declaration_template: "examples/simple/template.j2"

The declaration_template statement within the ninja.yaml provides the template location as examples/simple/template.j2. as3ninja expects to find the template at this location.

1$ docker run --rm --tty --interactive \
2    --volume \$(pwd)/examples:/examples \
3    simonkowallik/as3ninja:latest \
4    as3ninja transform -c /examples/simple/ninja.yaml \
5    | jq ."

Instructs docker to bind mount the $(pwd)/examples folder to /examples (line 2) for the container image simonkowallik/as3ninja:latest (line 3).

Docker then executes as3ninja transform -c /examples/simple/ninja.yaml (line 4) within the container and pipes the result to jq ..

_images/_docker_cli.svg

Todo

more cli examples

Command Line Usage

# for manual system wide installation (not recommended)
$ git clone https://github.com/simonkowallik/as3ninja
$ cd as3ninja
$ poetry build
$ pip3 install $(ls build/as3ninja*.whl)
# via PyPI using pip
$ pip=$(type -p pip3 || type -p pip)
$ $pip install as3ninja

API Usage

Use curl or httpie to query all available AS3 Schema versions:

$ http localhost:8000/api/schema/versions

$ curl -s localhost:8000/api/schema/versions | jq .
_images/_httpie_api.svg

Navigate to http://localhost:8000/api/docs and http://localhost:8000/api/redoc to explore the API.

Todo

Postman collection for API calls

Validating a declaration

Using an ephemeral container with docker run:

$ docker run -it --rm -v $PWD/declaration.json:/declaration.json \
    simonkowallik/as3ninja:latest \
    as3ninja validate -d /declaration.json
INFO: Validation passed for AS3 Schema version: 3.22.1

$ docker run -it --rm -v $PWD/declaration.json:/declaration.json \
    simonkowallik/as3ninja:latest \
    as3ninja validate -d /declaration.json --version 3.17.0
INFO: Validation passed for AS3 Schema version: 3.17.0

Using the API via curl:

# start the docker container on port 8000
docker run -d --rm -p 8000:8000 simonkowallik/as3ninja:latest
6dd7a4a9cc65f84974a122e0605dd74fe087a7e61e67298e529bcd96fa133c7

# POST declaration to /api/schema/validate endpoint (curl)
curl -s http://localhost:8000/api/schema/validate -d @declaration.json | jq .
{
  "valid": true,
  "error": null
}

# POST declaration to /api/schema/validate endpoint (httpie)
cat $PWD/examples/dynamic-irule/declaration.json | \
    http POST 'localhost:8000/api/schema/validate?version=3.20.0'
HTTP/1.1 200 OK
content-length: 27
content-type: application/json
date: Sun, 13 Sep 2020 12:14:03 GMT
server: uvicorn

{
    "error": null,
    "valid": true
}

Postman collection

An AS3 Ninja Postman collection is available on Github.

Python Package

Todo

Update usage as a module

To use AS3 Ninja in your python project:

 1from as3ninja.schema import AS3Schema, AS3ValidationError
 2from as3ninja.declaration import AS3Declaration
 3
 4# Declaration Template (str)
 5declaration_template = """
 6{
 7    "class": "AS3",
 8    "declaration": {
 9        "class": "ADC",
10        "schemaVersion": "3.11.0",
11        "id": "urn:uuid:{{ uuid() }}",
12        "{{ ninja.Tenantname }}": {
13            "class": "Tenant"
14        }
15    }
16}
17"""
18
19# Template Configuration (dict)
20template_configuration = {
21    "Tenantname": "MyTenant"
22}
23
24# generate the AS3 Declaration
25as3declaration = AS3Declaration(
26    template_configuration=template_configuration,
27    declaration_template=declaration_template
28    )
29
30from pprint import pprint
31# the transformed AS3 Declaration is available via the declaration attribute
32pprint(as3declaration.declaration)
33{'class': 'AS3',
34 'declaration': {'MyTenant': {'class': 'Tenant'},
35                 'class': 'ADC',
36                 'id': 'urn:uuid:f3850951-4a63-43ec-b2a3-28ab2c315479',
37                 'schemaVersion': '3.11.0'}}
38
39# create an AS3 schema instance
40as3schema = AS3Schema()
41
42# Validate the AS3 Declaration against the AS3 Schema (latest version)
43try:
44    as3schema.validate(declaration=as3declaration.declaration)
45except AS3ValidationError:
46    # an AS3ValidationError exception is raised when the validation fails
47    raise