├── .eslintignore ├── test ├── templatesets │ └── test │ │ ├── textData.txt.data │ │ ├── simple.yaml │ │ ├── extended.yaml │ │ ├── base.yaml │ │ ├── combine.yml │ │ ├── types.json │ │ ├── simple_udp.mst │ │ └── complex.yml ├── invalid_templatesets │ └── invalid │ │ └── invalid.yaml ├── setup-logging.js ├── githubMock.js ├── data_provider.js ├── schema_provider.js ├── transaction_logger.js ├── template_provider.js ├── gui_utils.js └── cli.js ├── .gitignore ├── .npmignore ├── lib ├── jsonpath-plus │ ├── jsonpath-node.js │ ├── LICENSE │ └── jsonpath.js ├── utils.js ├── resource_cache.js ├── html_stub.js ├── transaction_logger.js ├── data_provider.js ├── schema_provider.js ├── gui_utils.js └── github_provider.js ├── docs ├── README.md ├── getting_started.md ├── advanced.md ├── templating.md ├── api.md └── template_merging.md ├── scripts ├── build-fastbin.sh ├── getversion.sh └── auditProcessor.js ├── .eslintrc.js ├── .github └── workflows │ └── pipeline.yml ├── index.js ├── package.json ├── README.md ├── schema └── template.json ├── CHANGELOG.md ├── LICENSE └── cli.js /.eslintignore: -------------------------------------------------------------------------------- 1 | lib/jsonpath-plus/ -------------------------------------------------------------------------------- /test/templatesets/test/textData.txt.data: -------------------------------------------------------------------------------- 1 | Lorem ipsum 2 | -------------------------------------------------------------------------------- /test/invalid_templatesets/invalid/invalid.yaml: -------------------------------------------------------------------------------- 1 | title: Invalid 2 | template: {{foo} 3 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | .nyc_output 3 | .vscode/ 4 | coverage 5 | dist 6 | node_modules 7 | -------------------------------------------------------------------------------- /.npmignore: -------------------------------------------------------------------------------- 1 | test/* 2 | dist/* 3 | scripts/* 4 | .nyc_output 5 | test-output.txt 6 | .github 7 | -------------------------------------------------------------------------------- /lib/jsonpath-plus/jsonpath-node.js: -------------------------------------------------------------------------------- 1 | import vm from 'vm'; 2 | import {JSONPath} from './jsonpath.js'; 3 | 4 | JSONPath.prototype.vm = vm; 5 | 6 | export { 7 | JSONPath 8 | }; 9 | -------------------------------------------------------------------------------- /test/templatesets/test/simple.yaml: -------------------------------------------------------------------------------- 1 | title: Simple YAML file 2 | description: A simple template to test we can handle the .yaml file extension 3 | parameters: 4 | str_var: foo 5 | template: | 6 | {{str_var}} 7 | -------------------------------------------------------------------------------- /docs/README.md: -------------------------------------------------------------------------------- 1 | # FAST Core Documentation: 2 | 3 | * [Getting Started](getting_started.md) 4 | * [Module API](api.md) 5 | * [Authoring Templates](templating.md) 6 | * [Template Merging](template_merging.md) 7 | * [Advanced Features](advanced.md) -------------------------------------------------------------------------------- /test/templatesets/test/extended.yaml: -------------------------------------------------------------------------------- 1 | title: Main template 2 | contentType: application/json 3 | allOf: 4 | - $ref: "base.yaml#" 5 | definitions: 6 | extraData: 7 | title: Something Extra 8 | description: This is in addition to the base template 9 | template: | 10 | { 11 | "extraData": "{{extraData}}" 12 | } 13 | -------------------------------------------------------------------------------- /scripts/build-fastbin.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | set -eu 3 | 4 | version=$(./scripts/getversion.sh) 5 | outdir=./dist 6 | targets=node22-win,node22-macos,node22-linux,node22-alpine 7 | 8 | # Generate binaries 9 | pkg . -t ${targets} -o "${outdir}/fast-${version}" 10 | 11 | # Generate sha256 hashes 12 | cd "${outdir}" 13 | for bin in $(ls "fast-${version}-"*) 14 | do 15 | sha256sum "${bin}" > "${bin}.sha256" 16 | done 17 | -------------------------------------------------------------------------------- /scripts/getversion.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | set -eu 3 | 4 | full_version=$(node -e "console.log(require('./package.json').version)") 5 | version="$(echo $full_version | cut -d - -f 1)" 6 | last_tag="$(git describe --tags --always --abbrev=0)" 7 | num_commits_from_tag=$(git rev-list $last_tag.. --count) 8 | if [[ "$last_tag" == "v${version}"* ]]; then 9 | version="$(echo $last_tag | tail -c +2)" 10 | fi 11 | if [ "$num_commits_from_tag" -ne 0 ]; then 12 | version="$version.dev$num_commits_from_tag" 13 | fi 14 | 15 | echo ${version} 16 | -------------------------------------------------------------------------------- /test/templatesets/test/base.yaml: -------------------------------------------------------------------------------- 1 | title: Base Template 2 | contentType: application/json 3 | definitions: 4 | name: 5 | title: Object Name 6 | description: Give this thing a great name! 7 | minLength: 1 8 | description: 9 | title: Object Description 10 | description: What is this object about? (can be empty) 11 | number: 12 | title: Number please! 13 | description: A number would be grand, but please be positive. 14 | minimum: 0 15 | template: | 16 | { 17 | "name": "{{name}}", 18 | "description": "{{description}}", 19 | "integer": {{number::integer}}, 20 | "port": {{port:types:port}} 21 | } 22 | -------------------------------------------------------------------------------- /test/templatesets/test/combine.yml: -------------------------------------------------------------------------------- 1 | title: Combining Templates 2 | description: An example of how to combine templates 3 | allOf: 4 | - title: "Base Props" 5 | template: "{{name}}" 6 | definitions: 7 | name: 8 | title: Name 9 | description: The application name 10 | oneOf: 11 | - title: "Template A" 12 | template: "{{prop1::string}}" 13 | definitions: 14 | prop1: 15 | title: "Property 1" 16 | - title: "Template B" 17 | template: "{{prop2::integer}}" 18 | definitions: 19 | prop2: 20 | title: "Property 2" 21 | anyOf: 22 | - {} 23 | - title: "Mixin" 24 | template: "{{mixin_prop}}" 25 | -------------------------------------------------------------------------------- /test/templatesets/test/types.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "http://json-schema.org/draft-07/hyper-schema", 3 | "definitions": { 4 | "port": { 5 | "type": "integer", 6 | "minimum": 0, 7 | "maximum": 65535, 8 | "default": 443 9 | }, 10 | "ipv4_addr": { 11 | "title": "IPv4 Address", 12 | "type": "string" 13 | }, 14 | "ipv6_addr": { 15 | "title": "IPv6 Address", 16 | "type": "string" 17 | }, 18 | "ip_addr": { 19 | "anyOf": [ 20 | {"$ref": "#/definitions/ipv4_addr"}, 21 | {"$ref": "#/definitions/ipv6_addr"} 22 | ] 23 | }, 24 | "bool_section": { 25 | "type": "boolean" 26 | } 27 | } 28 | } 29 | -------------------------------------------------------------------------------- /lib/utils.js: -------------------------------------------------------------------------------- 1 | /* Copyright 2021 F5 Networks, Inc. 2 | * 3 | * Licensed under the Apache License, Version 2.0 (the "License"); 4 | * you may not use this file except in compliance with the License. 5 | * You may obtain a copy of the License at 6 | * 7 | * http://www.apache.org/licenses/LICENSE-2.0 8 | * 9 | * Unless required by applicable law or agreed to in writing, software 10 | * distributed under the License is distributed on an "AS IS" BASIS, 11 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | * See the License for the specific language governing permissions and 13 | * limitations under the License. 14 | */ 15 | 16 | 'use strict'; 17 | 18 | /** 19 | * Strip the extension off of a file 20 | * 21 | * @param {string} fileName - the file name 22 | * @returns {string} 23 | */ 24 | function stripExtension(fileName) { 25 | return fileName.split('.').slice(0, -1).join('.'); 26 | } 27 | 28 | module.exports = { 29 | stripExtension 30 | }; 31 | -------------------------------------------------------------------------------- /.eslintrc.js: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | env: { 3 | es2022: true, 4 | mocha: true, 5 | node: true 6 | }, 7 | 8 | parserOptions: { 9 | ecmaVersion: 2023, 10 | sourceType: 'script' 11 | }, 12 | 13 | rules: { 14 | indent: ['error', 4], 15 | 'no-param-reassign': 'off', 16 | 'class-methods-use-this': 'off', 17 | 'no-underscore-dangle': 'off', 18 | 19 | // Allow function declarations at the bottom of a file. They are hoisted in ES6. 20 | 'no-use-before-define': ['error', { functions: false }], 21 | 22 | // named funcs in stacktrace 23 | 'func-names': ['error', 'as-needed'], 24 | 25 | 'function-call-argument-newline': ['error', 'consistent'], 26 | 'function-paren-newline': ['error', 'consistent'], 27 | 28 | // only set strict mode when necessary 29 | 'strict': ['error', 'global'], 30 | 31 | 'max-len': ['error', 120, 2, { 32 | ignoreUrls: true, 33 | ignoreComments: false, 34 | ignoreRegExpLiterals: true, 35 | ignoreStrings: true, 36 | ignoreTemplateLiterals: true 37 | }] 38 | } 39 | }; 40 | -------------------------------------------------------------------------------- /test/setup-logging.js: -------------------------------------------------------------------------------- 1 | /* Copyright 2021 F5 Networks, Inc. 2 | * 3 | * Licensed under the Apache License, Version 2.0 (the "License"); 4 | * you may not use this file except in compliance with the License. 5 | * You may obtain a copy of the License at 6 | * 7 | * http://www.apache.org/licenses/LICENSE-2.0 8 | * 9 | * Unless required by applicable law or agreed to in writing, software 10 | * distributed under the License is distributed on an "AS IS" BASIS, 11 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | * See the License for the specific language governing permissions and 13 | * limitations under the License. 14 | */ 15 | 16 | 'use strict'; 17 | 18 | /* eslint-disable */ 19 | 20 | const origLogFunc = console.log; 21 | let output = ''; 22 | 23 | beforeEach(function() { 24 | output = ''; 25 | console.log = (msg) => { 26 | if (typeof(msg) === 'object') { 27 | msg = JSON.stringify(msg, null, 2); 28 | } 29 | output += `${msg}\n`; 30 | }; 31 | }); 32 | 33 | afterEach(function() { 34 | console.log = origLogFunc; 35 | if (this.currentTest.state === 'failed') { 36 | console.log(output); 37 | } 38 | }); 39 | -------------------------------------------------------------------------------- /lib/jsonpath-plus/LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2011-2019 Stefan Goessner, Subbu Allamaraju, Mike Brevoort, 4 | Robert Krahn, Brett Zamir, Richard Schneider 5 | 6 | Permission is hereby granted, free of charge, to any person obtaining a copy 7 | of this software and associated documentation files (the "Software"), to deal 8 | in the Software without restriction, including without limitation the rights 9 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 10 | copies of the Software, and to permit persons to whom the Software is 11 | furnished to do so, subject to the following conditions: 12 | 13 | The above copyright notice and this permission notice shall be included in all 14 | copies or substantial portions of the Software. 15 | 16 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 21 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 22 | SOFTWARE. 23 | -------------------------------------------------------------------------------- /test/templatesets/test/simple_udp.mst: -------------------------------------------------------------------------------- 1 | {{! 2 | Simple UDP load balancer using the same port on client and server side. 3 | Uses AS3 template: udp. 4 | }} 5 | { 6 | "class": "AS3", 7 | "action": "deploy", 8 | "declaration": { 9 | "class": "ADC", 10 | "schemaVersion": "3.0.0", 11 | "id": "0123-4567-8910", 12 | "label": "UDP_DNS_Sample", 13 | "remark": "Sample of a UDP DNS Load Balancer Service", 14 | "{{tenant_name}}": { 15 | "class": "Tenant", 16 | "{{application_name}}": { 17 | "class": "Application", 18 | "template": "udp", 19 | "serviceMain": { 20 | "class": "Service_UDP", 21 | "virtualAddresses": [ 22 | "{{virtual_address:types:ip_addr}}" 23 | ], 24 | "virtualPort": {{virtual_port::integer}}, 25 | "pool": "Pool1" 26 | }, 27 | "Pool1": { 28 | "class": "Pool", 29 | "monitors": [ 30 | "icmp" 31 | ], 32 | "members": [ 33 | { 34 | "serverAddresses": [ 35 | {{#server_addresses}} 36 | "{{.}}", 37 | {{/server_addresses}} 38 | ], 39 | "servicePort": {{service_port:types:port}} 40 | } 41 | ] 42 | } 43 | } 44 | } 45 | } 46 | } 47 | -------------------------------------------------------------------------------- /.github/workflows/pipeline.yml: -------------------------------------------------------------------------------- 1 | name: Pipeline 2 | 3 | on: [push, pull_request] 4 | 5 | jobs: 6 | test: 7 | runs-on: ubuntu-latest 8 | strategy: 9 | matrix: 10 | node-version: [22.x] 11 | steps: 12 | - uses: actions/checkout@v2 13 | - name: Setup Node.js ${{ matrix.node-version }} 14 | uses: actions/setup-node@v1 15 | with: 16 | node-version: ${{ matrix.node-version }} 17 | - run: npm ci 18 | - run: npm run lint 19 | - run: npm run coverage.all 20 | audit: 21 | runs-on: ubuntu-latest 22 | continue-on-error: true 23 | strategy: 24 | matrix: 25 | node-version: [22.x] 26 | steps: 27 | - uses: actions/checkout@v2 28 | - name: Setup Node.js ${{ matrix.node-version }} 29 | uses: actions/setup-node@v1 30 | with: 31 | node-version: ${{ matrix.node-version }} 32 | - run: npm ci && npm run audit-production 33 | publish: 34 | if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags') 35 | needs: [test, audit] 36 | runs-on: ubuntu-latest 37 | steps: 38 | - uses: actions/checkout@v2 39 | - name: Setup Node.js ${{ matrix.node-version }} 40 | uses: actions/setup-node@v1 41 | with: 42 | node-version: 22 43 | registry-url: https://registry.npmjs.org/ 44 | - run: npm ci 45 | - run: npm publish --access public 46 | env: 47 | NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}} 48 | -------------------------------------------------------------------------------- /lib/resource_cache.js: -------------------------------------------------------------------------------- 1 | /* Copyright 2021 F5 Networks, Inc. 2 | * 3 | * Licensed under the Apache License, Version 2.0 (the "License"); 4 | * you may not use this file except in compliance with the License. 5 | * You may obtain a copy of the License at 6 | * 7 | * http://www.apache.org/licenses/LICENSE-2.0 8 | * 9 | * Unless required by applicable law or agreed to in writing, software 10 | * distributed under the License is distributed on an "AS IS" BASIS, 11 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | * See the License for the specific language governing permissions and 13 | * limitations under the License. 14 | */ 15 | 16 | 'use strict'; 17 | 18 | class ResourceCache { 19 | constructor(asyncFetch) { 20 | // used for caching AS3 TemplateEngine objects 21 | this.cached = {}; 22 | this.cache_limit = 100; 23 | this.asyncFetch = asyncFetch; 24 | } 25 | 26 | fetch(key) { 27 | return (() => { 28 | if (!this.cached[key]) { 29 | this.cached[key] = this.asyncFetch(key) 30 | .then((resource) => { 31 | this.cached[key] = resource; 32 | const allKeys = Object.keys(this.cached); 33 | const oldestKey = allKeys.shift(); 34 | if (allKeys.length > this.cache_limit) delete this.cached[oldestKey]; 35 | return resource; 36 | }); 37 | } 38 | return Promise.resolve(this.cached[key]); 39 | })(); 40 | } 41 | 42 | invalidate() { 43 | this.cached = {}; 44 | } 45 | } 46 | 47 | module.exports = { 48 | ResourceCache 49 | }; 50 | -------------------------------------------------------------------------------- /test/templatesets/test/complex.yml: -------------------------------------------------------------------------------- 1 | title: chat window 2 | parameters: 3 | title: My Chat Window 4 | chatlog: 5 | - name: ricky 6 | msg: it's not rocket appliances 7 | - name: bubbles 8 | msg: patrick swayze uses illegal parts 9 | - name: ricky 10 | msg: sebastian bach wants to buy our stuff 11 | members: 12 | - ricky 13 | - julian 14 | - bubbles 15 | - cory 16 | - trevor 17 | array_section: 18 | - a 19 | - b 20 | definitions: 21 | chatroom: 22 | template: | 23 |
24 | {{#members}} 25 |
26 | {{.}} 27 |
28 | {{/members}} 29 |
30 | chatlog: 31 | template: | 32 |
33 |
{{name}}
34 |
{{msg}}
35 |
36 | fromFile: 37 | dataFile: textData.txt 38 | template: | 39 | 40 | 41 | 53 | 54 |

{{title}}

55 | {{^skip_section}} 56 |
Skip Me
57 | {{/skip_section}} 58 | 63 |
64 |
65 | {{> chatlog }} 66 |
67 |
68 | {{> chatroom }} 69 |
70 |
71 |
72 | {{fromFile}} 73 |
74 | 75 | 76 | -------------------------------------------------------------------------------- /index.js: -------------------------------------------------------------------------------- 1 | /* Copyright 2021 F5 Networks, Inc. 2 | * 3 | * Licensed under the Apache License, Version 2.0 (the "License"); 4 | * you may not use this file except in compliance with the License. 5 | * You may obtain a copy of the License at 6 | * 7 | * http://www.apache.org/licenses/LICENSE-2.0 8 | * 9 | * Unless required by applicable law or agreed to in writing, software 10 | * distributed under the License is distributed on an "AS IS" BASIS, 11 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | * See the License for the specific language governing permissions and 13 | * limitations under the License. 14 | */ 15 | 16 | 'use strict'; 17 | 18 | const dataStores = require('@f5devcentral/atg-storage'); 19 | 20 | const FsSchemaProvider = require('./lib/schema_provider').FsSchemaProvider; 21 | const { 22 | BaseTemplateProvider, 23 | FsTemplateProvider, 24 | FsSingleTemplateProvider, 25 | DataStoreTemplateProvider, 26 | CompositeTemplateProvider 27 | } = require('./lib/template_provider'); 28 | const { GitHubTemplateProvider, GitHubSchemaProvider } = require('./lib/github_provider'); 29 | const { 30 | Template, mergeStrategies, postProcessStrategies, transformStrategies 31 | } = require('./lib/template'); 32 | const guiUtils = require('./lib/gui_utils'); 33 | const TransactionLogger = require('./lib/transaction_logger'); 34 | 35 | module.exports = { 36 | FsSchemaProvider, 37 | BaseTemplateProvider, 38 | FsTemplateProvider, 39 | FsSingleTemplateProvider, 40 | DataStoreTemplateProvider, 41 | CompositeTemplateProvider, 42 | GitHubTemplateProvider, 43 | GitHubSchemaProvider, 44 | Template, 45 | mergeStrategies, 46 | postProcessStrategies, 47 | transformStrategies, 48 | guiUtils, 49 | dataStores, 50 | TransactionLogger 51 | }; 52 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@f5devcentral/f5-fast-core", 3 | "version": "0.26.0", 4 | "author": "F5 Networks", 5 | "license": "Apache-2.0", 6 | "repository": "github:f5devcentral/f5-fast-core", 7 | "main": "index.js", 8 | "description": "The core module for F5 Application Services Templates", 9 | "scripts": { 10 | "audit-production": "npm audit --production --json > .auditReport.json; npx f5-fast-audit-npm", 11 | "test": "mocha --exclude test/cli.js", 12 | "test.cli": "mocha test/setup-logging.js test/cli.js", 13 | "test.all": "mocha", 14 | "lint": "eslint lib test index.js cli.js --ignore-pattern jsoneditor.js", 15 | "buildbin": "./scripts/build-fastbin.sh", 16 | "coverage": "nyc -r text -r html npm test", 17 | "coverage.all": "nyc -r text -r html npm run test.all" 18 | }, 19 | "keywords": [ 20 | "as3", 21 | "f5", 22 | "rest", 23 | "api" 24 | ], 25 | "bin": { 26 | "fast": "./cli.js", 27 | "f5-fast-audit-npm": "./scripts/auditProcessor.js" 28 | }, 29 | "devDependencies": { 30 | "chai": "^4.3.10", 31 | "chai-as-promised": "^7.1.1", 32 | "eslint": "^8.50.0", 33 | "eslint-plugin-import": "^2.28.1", 34 | "mocha": "^10.2.0", 35 | "nock": "^13.3.3", 36 | "nyc": "^15.1.0" 37 | }, 38 | "nyc": { 39 | "all": true, 40 | "include": [ 41 | "lib/**/*.js", 42 | "cli.js" 43 | ], 44 | "exclude": [ 45 | "lib/jsoneditor.js" 46 | ] 47 | }, 48 | "dependencies": { 49 | "@apidevtools/json-schema-ref-parser": "9.0.9", 50 | "@f5devcentral/atg-storage": "^1.3.9", 51 | "adm-zip": "^0.5.10", 52 | "ajv": "^6.12.6", 53 | "axios": "0.30.2", 54 | "deepmerge": "^4.3.1", 55 | "js-yaml": "^4.1.0", 56 | "math-expression-evaluator": "^1.4.0", 57 | "merge-lite": "^1.0.2", 58 | "mustache": "^4.2.0", 59 | "yargs": "^17.7.2" 60 | } 61 | } 62 | -------------------------------------------------------------------------------- /lib/html_stub.js: -------------------------------------------------------------------------------- 1 | /* Copyright 2021 F5 Networks, Inc. 2 | * 3 | * Licensed under the Apache License, Version 2.0 (the "License"); 4 | * you may not use this file except in compliance with the License. 5 | * You may obtain a copy of the License at 6 | * 7 | * http://www.apache.org/licenses/LICENSE-2.0 8 | * 9 | * Unless required by applicable law or agreed to in writing, software 10 | * distributed under the License is distributed on an "AS IS" BASIS, 11 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | * See the License for the specific language governing permissions and 13 | * limitations under the License. 14 | */ 15 | 16 | /* eslint-disable */ 17 | 18 | 'use strict'; 19 | 20 | const htmlData = ` 21 | 22 | 23 | 24 | 25 | Template Preview 26 | 27 | 28 | 29 | 30 |
31 | 32 | 33 | 34 | 49 | 50 | 51 | `; 52 | 53 | module.exports = { 54 | htmlData 55 | }; 56 | -------------------------------------------------------------------------------- /lib/transaction_logger.js: -------------------------------------------------------------------------------- 1 | /* Copyright 2021 F5 Networks, Inc. 2 | * 3 | * Licensed under the Apache License, Version 2.0 (the "License"); 4 | * you may not use this file except in compliance with the License. 5 | * You may obtain a copy of the License at 6 | * 7 | * http://www.apache.org/licenses/LICENSE-2.0 8 | * 9 | * Unless required by applicable law or agreed to in writing, software 10 | * distributed under the License is distributed on an "AS IS" BASIS, 11 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | * See the License for the specific language governing permissions and 13 | * limitations under the License. 14 | */ 15 | 16 | 'use strict'; 17 | 18 | class TransactionLogger { 19 | constructor(onEnter, onExit) { 20 | this.onEnterCb = onEnter || (() => {}); 21 | this.onExitCb = onExit || (() => {}); 22 | this.transactions = {}; 23 | this._nextTid = 0; 24 | } 25 | 26 | _getTime() { 27 | return new Date(); 28 | } 29 | 30 | _deltaTime(startTime, endTime) { 31 | return endTime.getTime() - startTime.getTime(); 32 | } 33 | 34 | enter(transaction, tid) { 35 | if (!transaction) { 36 | throw new Error('Missing required argument transaction'); 37 | } 38 | tid = tid || 0; 39 | const enterTime = this._getTime(); 40 | this.onEnterCb(transaction, enterTime); 41 | this.transactions[`${transaction}-${tid}`] = enterTime; 42 | } 43 | 44 | exit(transaction, tid) { 45 | if (!transaction) { 46 | throw new Error('Missing required argument transaction'); 47 | } 48 | tid = tid || 0; 49 | const tkey = `${transaction}-${tid}`; 50 | if (!this.transactions[tkey]) { 51 | throw new Error('exit() called without enter()'); 52 | } 53 | const exitTime = this._getTime(); 54 | const enterTime = this.transactions[tkey]; 55 | this.onExitCb(transaction, exitTime, this._deltaTime(enterTime, exitTime)); 56 | delete this.transactions[tkey]; 57 | } 58 | 59 | enterPromise(transaction, promise) { 60 | const tid = this._nextTid; 61 | this._nextTid += 1; 62 | this.enter(transaction, tid); 63 | return promise 64 | .finally(() => this.exit(transaction, tid)); 65 | } 66 | } 67 | 68 | module.exports = TransactionLogger; 69 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ![Pipeline](https://github.com/f5devcentral/f5-fast-core/workflows/Pipeline/badge.svg) 2 | ![npm](https://img.shields.io/npm/dw/@f5devcentral/f5-fast-core) 3 | ![NPM](https://img.shields.io/npm/l/@f5devcentral/f5-fast-core?registry_uri=https%3A%2F%2Fregistry.npmjs.com) 4 | 5 | # F5 Application Services Templates (FAST) SDK 6 | 7 | This module provides a framework for handling templates. 8 | 9 | ## Documentation 10 | 11 | Documentation for BIG-IP FAST Core can be found [here](docs/README.md). 12 | 13 | ## Features 14 | 15 | * Parses Mustache templates and an extended template format (in YAML) 16 | * Generates a parameter schema from parsed template data 17 | * Supports Mustache partials and sections 18 | * Renders templates with user-provided parameters 19 | * Validates user-provided parameters against generated parameter schema 20 | * Includes a [command line interface](docs/getting_started.md#cli) 21 | 22 | ## Installation 23 | 24 | To install this module run: 25 | 26 | ```bash 27 | npm install @f5devcentral/f5-fast-core 28 | ``` 29 | 30 | ## Development 31 | 32 | * To check for lint errors run `npm run lint` 33 | * To run unit tests use `npm test` 34 | 35 | Both of these are run as part of the CI pipeline for this repo. 36 | 37 | ## License 38 | 39 | [Apache License 2.0](https://choosealicense.com/licenses/apache-2.0/) 40 | 41 | ## Copyright 42 | 43 | Copyright 2014-2020 F5 Networks Inc. 44 | 45 | 46 | ### F5 Networks Contributor License Agreement 47 | 48 | Before you start contributing to any project sponsored by F5 Networks, Inc. (F5) on GitHub, you will need to sign a Contributor License Agreement (CLA). 49 | 50 | If you are signing as an individual, we recommend that you talk to your employer (if applicable) before signing the CLA since some employment agreements may have restrictions on your contributions to other projects. 51 | Otherwise by submitting a CLA you represent that you are legally entitled to grant the licenses recited therein. 52 | 53 | If your employer has rights to intellectual property that you create, such as your contributions, you represent that you have received permission to make contributions on behalf of that employer, that your employer has waived such rights for your contributions, or that your employer has executed a separate CLA with F5. 54 | 55 | If you are signing on behalf of a company, you represent that you are legally entitled to grant the license recited therein. 56 | You represent further that each employee of the entity that submits contributions is authorized to submit such contributions on behalf of the entity pursuant to the CLA. 57 | -------------------------------------------------------------------------------- /test/githubMock.js: -------------------------------------------------------------------------------- 1 | /* Copyright 2021 F5 Networks, Inc. 2 | * 3 | * Licensed under the Apache License, Version 2.0 (the "License"); 4 | * you may not use this file except in compliance with the License. 5 | * You may obtain a copy of the License at 6 | * 7 | * http://www.apache.org/licenses/LICENSE-2.0 8 | * 9 | * Unless required by applicable law or agreed to in writing, software 10 | * distributed under the License is distributed on an "AS IS" BASIS, 11 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | * See the License for the specific language governing permissions and 13 | * limitations under the License. 14 | */ 15 | 16 | 'use strict'; 17 | 18 | const fs = require('fs'); 19 | const nock = require('nock'); 20 | 21 | function nockGitHubAPI(repo, filesPath) { 22 | const gatherFiles = (dir, root) => { 23 | const files = []; 24 | const dirs = fs.readdirSync(dir, { withFileTypes: true }); 25 | dirs.forEach((d) => { 26 | const entryPath = `${dir}/${d.name}`; 27 | files.push({ 28 | name: d.name, 29 | path: entryPath.replace(`${root}/`, ''), 30 | type: (d.isFile()) ? 'file' : 'dir' 31 | }); 32 | 33 | if (d.isDirectory()) { 34 | files.push(...gatherFiles(entryPath, root)); 35 | } else if (d.isFile()) { 36 | const fileData = fs.readFileSync(entryPath, { encoding: 'utf8' }); 37 | files[files.length - 1].content = Buffer.from(fileData, 'utf8').toString('base64'); 38 | } 39 | }); 40 | 41 | return files; 42 | }; 43 | 44 | const files = gatherFiles(filesPath, filesPath); 45 | 46 | const uriParts = (uri) => { 47 | const parts = uri.split('/'); 48 | 49 | return { 50 | repo: `${parts[2]}/${parts[3]}`, 51 | directory: parts[5], 52 | file: parts[6] 53 | }; 54 | }; 55 | 56 | nock('https://api.github.com', { 57 | reqheaders: { 58 | authorization: 'Token secret' 59 | } 60 | }) 61 | .persist() 62 | .get(/repos\/.*\/contents\/.*/) 63 | .reply((uri) => { 64 | const req = uriParts(uri); 65 | if (req.repo !== repo) { 66 | return [ 67 | 400, 68 | { 69 | message: `Expected repo ${repo} but got ${req.repo}` 70 | } 71 | ]; 72 | } 73 | 74 | if (req.file) { 75 | const retFile = files 76 | .filter(x => x.path === `${req.directory}/${req.file}`)[0]; 77 | return [ 78 | 200, 79 | retFile 80 | ]; 81 | } 82 | 83 | const data = files 84 | .filter(x => x.path.startsWith(req.directory)); 85 | return [ 86 | 200, 87 | data 88 | ]; 89 | }); 90 | } 91 | 92 | module.exports = { 93 | nockGitHubAPI 94 | }; 95 | -------------------------------------------------------------------------------- /docs/getting_started.md: -------------------------------------------------------------------------------- 1 | # Getting Started 2 | 3 | ## Installation 4 | 5 | To install this module run: 6 | 7 | ```bash 8 | npm install @f5devcentral/f5-fast-core 9 | ``` 10 | 11 | ## CLI 12 | 13 | A command line interface is provided via a `fast` binary. 14 | 15 | FAST can render a basic template with the CLI. Here is an example using a template file named hello.yaml: 16 | ```yaml 17 | parameters: 18 | message: Hello! 19 | definitions: 20 | body: 21 | template: 22 | 23 |

{{message}}

24 | 25 | template: | 26 | 27 | {{> body}} 28 | 29 | ``` 30 | 31 | With this command to render the template: 32 | ```bash 33 | fast render hello.yaml 34 | ``` 35 | 36 | For help, like the text provided below, is also accessed via `fast --help`: 37 | 38 | 39 | ``` 40 | fast 41 | 42 | Commands: 43 | fast validate validate given template source file 44 | fast schema get template parameter schema for given template source file 45 | fast guiSchema get template parameter schema (modified for use with JSON Editor) for given template source file 46 | fast validateParameters validate supplied template parameters with given template 47 | fast render [parameterFile] render given template file with supplied parameters 48 | fast validateTemplateSet validate supplied template set 49 | fast htmlpreview [parameterFile] generate a static HTML file with a preview editor to standard out 50 | fast packageTemplateSet [dst] build a package for a given template set 51 | 52 | Options: 53 | --help Show help [boolean] 54 | --version Show version number [boolean] 55 | ``` 56 | 57 | For more information on a given command use the `--help` flag combined with a command: 58 | 59 | ```bash 60 | fast --help 61 | ``` 62 | 63 | The CLI can also be accessed by executing `cli.js`. 64 | For example: 65 | 66 | ```bash 67 | ./cli.js render path/to/template 68 | ``` 69 | 70 | ## ContentTypes 71 | 72 | When FAST renders it is doing string replacement via Mustache, which is agnostic to the output type. However, specifying a contentType in the template can enable some additional features: 73 | 74 | * Post-processing steps (e.g., strip dangling commas for JSON) 75 | * Smarter merges 76 | * Smarter handling of some data types 77 | 78 | Here is an example of using application/json for the content type: 79 | 80 | Template: 81 | ```yaml 82 | title: Members in JSON List 83 | contentType: application/json 84 | template: | 85 | { 86 | "members": [ 87 | {{#members}} 88 | { "ipAddr": "{{ . }}" }, 89 | {{/members}} 90 | ] 91 | } 92 | ``` 93 | 94 | Parameters: 95 | ```yaml 96 | members: 97 | - 10.0.0.1 98 | - 10.0.0.2 99 | - 10.0.0.3 100 | ``` 101 | 102 | Output: 103 | ``` 104 | { 105 | "members": [ 106 | { 107 | "ipAddr": "10.0.0.1" 108 | }, 109 | { 110 | "ipAddr": "10.0.0.2" 111 | }, 112 | { 113 | "ipAddr": "10.0.0.3" 114 | } 115 | ] 116 | } 117 | ``` -------------------------------------------------------------------------------- /test/data_provider.js: -------------------------------------------------------------------------------- 1 | /* Copyright 2021 F5 Networks, Inc. 2 | * 3 | * Licensed under the Apache License, Version 2.0 (the "License"); 4 | * you may not use this file except in compliance with the License. 5 | * You may obtain a copy of the License at 6 | * 7 | * http://www.apache.org/licenses/LICENSE-2.0 8 | * 9 | * Unless required by applicable law or agreed to in writing, software 10 | * distributed under the License is distributed on an "AS IS" BASIS, 11 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | * See the License for the specific language governing permissions and 13 | * limitations under the License. 14 | */ 15 | 16 | /* eslint-disable prefer-arrow-callback */ 17 | /* eslint-disable func-names */ 18 | /* eslint-disable no-console */ 19 | 20 | 'use strict'; 21 | 22 | const fs = require('fs'); 23 | const chai = require('chai'); 24 | const chaiAsPromised = require('chai-as-promised'); 25 | 26 | chai.use(chaiAsPromised); 27 | const assert = chai.assert; 28 | 29 | const StorageMemory = require('@f5devcentral/atg-storage').StorageMemory; 30 | const { FsDataProvider, DataStoreDataProvider } = require('../lib/data_provider'); 31 | 32 | const datasPath = './test/templatesets/test/'; 33 | 34 | function runSharedTests(createProvider) { 35 | it('construct', function () { 36 | const provider = createProvider(); 37 | assert.ok(provider); 38 | }); 39 | it('load_single', function () { 40 | const provider = createProvider(); 41 | return provider.fetch('textData.txt') 42 | .then((data) => { 43 | assert.strictEqual(data, 'Lorem ipsum\n'); 44 | }); 45 | }); 46 | it('load_single_bad', function () { 47 | const provider = createProvider(); 48 | return assert.isRejected(provider.fetch('does_not_exist')); 49 | }); 50 | it('load_list', function () { 51 | const provider = createProvider(); 52 | return assert.becomes(provider.list(), [ 53 | 'textData.txt' 54 | ]); 55 | }); 56 | } 57 | 58 | describe('data provider tests', function () { 59 | describe('FsDataProvider', function () { 60 | runSharedTests(() => new FsDataProvider(datasPath)); 61 | it('bad_data_path', function () { 62 | const provider = new FsDataProvider('bad/path'); 63 | return Promise.all([ 64 | assert.isRejected(provider.list()), 65 | assert.isRejected(provider.fetch('f5')) 66 | ]); 67 | }); 68 | }); 69 | 70 | describe('DataStoreDataProvider', function () { 71 | const createDataStore = () => new StorageMemory({ 72 | test: { 73 | templates: {}, 74 | dataFiles: fs.readdirSync(`${datasPath}`).filter(x => x.endsWith('.data')).reduce( 75 | (acc, fname) => { 76 | acc[fname.replace(/.data$/, '')] = fs.readFileSync(`${datasPath}/${fname}`, { encoding: 'utf8' }); 77 | return acc; 78 | }, {} 79 | ) 80 | } 81 | }); 82 | runSharedTests(() => new DataStoreDataProvider(createDataStore(), 'test')); 83 | it('bad_ts_name', function () { 84 | const provider = new DataStoreDataProvider(createDataStore(), 'does_not_exist'); 85 | return Promise.all([ 86 | assert.isRejected(provider.list()), 87 | assert.isRejected(provider.fetch('textData')) 88 | ]); 89 | }); 90 | }); 91 | }); 92 | -------------------------------------------------------------------------------- /docs/advanced.md: -------------------------------------------------------------------------------- 1 | # Advanced Features 2 | 3 | This page offers more advanced features that do not appear in other related documentation for FAST Core. 4 | 5 | ## HTTP Fetch 6 | 7 | To resolve external URLs in templates, a `Template.fetchHttp()` is available. 8 | This will take any definition with a `url` property, resolve it, and return an object of the results. 9 | 10 | ```javascript 11 | const fast = require('@f5devcentral/f5-fast-core'); 12 | 13 | const yamldata = ` 14 | definitions: 15 | var: 16 | url: http://example.com/resource 17 | pathQuery: $.foo 18 | template: | 19 | {{var}} 20 | `; 21 | 22 | fast.Template.loadYaml(yamldata) 23 | .then(template => Promise.all[( 24 | Promise.resolve(template), 25 | () => template.fetchHttp() 26 | )]) 27 | .then(([template, httpParams]) => { 28 | console.log(template.render(httpParams)); 29 | }); 30 | ``` 31 | 32 | A `Template.fetchAndRender()` convenience function is also available to do fetchHttp() and render() in a single function call. 33 | 34 | ```javascript 35 | const fast = require('@f5devcentral/f5-fast-core'); 36 | 37 | const yamldata = ` 38 | definitions: 39 | var: 40 | url: http://example.com/resource 41 | pathQuery: $.foo 42 | template: | 43 | {{var}} 44 | `; 45 | 46 | fast.Template.loadYaml(yamldata) 47 | .then(template => template.fetchAndRender()) 48 | .then((rendered) => { 49 | console.log(rendered); 50 | }); 51 | ``` 52 | 53 | ## HTTP Forward 54 | 55 | It is common to want to submit the rendered template result to an HTTP endpoint. 56 | `f5-fast-core` makes this simpler with `Template.forwardHttp()`. 57 | This function will: 58 | 59 | * Resolve external URLs with `Template.fetchHttp()` 60 | * Render the template result 61 | * Forward the rendered result as a `POST` (by default) to the endpoint defined by the template's `httpForward` property 62 | 63 | ```javascript 64 | const fast = require('@f5devcentral/f5-fast-core'); 65 | 66 | const yamldata = ` 67 | httpForward: 68 | url: http://example.com/resource 69 | definitions: 70 | var: 71 | default: foo 72 | template: | 73 | {{var}} 74 | `; 75 | 76 | fast.Template.loadYaml(yamldata) 77 | .then(template => template.forwardHttp()); // POST "foo" to http://example.com/resource 78 | ``` 79 | 80 | ## HTTP Calls to External Resources 81 | Some template parameters may be sourced from other places, such as external APIs or databases. 82 | 83 | A Template.fetchHttp() method does an HTTP request for each parameter definition that has a url property returning a parameter object with the response results. The value used from a response can be altered by specifying a JSONPath query in an optional pathQuery property of the parameter definition. url can also be an object matching Node’s http.request() options object. 84 | ```yaml 85 | type: object 86 | properties: 87 | url: 88 | description: HTTP resource to call to fetch data. 89 | oneOf: 90 | - type: string 91 | - type: object # looks like Node request options 92 | pathQuery: 93 | type: string 94 | description: JSONPath of data to be fetched, must match schema 95 | ``` 96 | 97 | ## Calculating Template Set Hashes 98 | 99 | Calculate the hash of a local Template Set with `FsSingleTemplateProvider` like this: 100 | 101 | ```javascript 102 | const fast = require('@f5devcentral/f5-fast-core'); 103 | 104 | const templateSetPath = '/path/to/templateSet'; 105 | const templateProvider = new fast.FsSingleTemplateProvider(templateSetPath); 106 | 107 | templateProvider.getSetData('templateSetName') 108 | .then((tsData) => { 109 | console.log(tsData.hash) 110 | }); 111 | ``` 112 | 113 | > **Note:** Despite loading a single template set, a template set name must still be provided when querying the provider. 114 | -------------------------------------------------------------------------------- /schema/template.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "http://json-schema.org/draft-07/schema#", 3 | "$id": "templateSchema", 4 | "title": "tempateSchema schema definition", 5 | "oneOf": [ 6 | { 7 | "allOf": [ 8 | { 9 | "$ref": "http://json-schema.org/draft-07/schema#" 10 | }, 11 | { 12 | "type": "object", 13 | "properties": { 14 | "view": { 15 | "type": "object", 16 | "description": "a sample view to render the template with" 17 | }, 18 | "template": { 19 | "type": "string", 20 | "format": "mustache", 21 | "description": "a mustache template component" 22 | }, 23 | "definitions": { 24 | "type": "object", 25 | "additionalProperties": { 26 | "$ref": "#" 27 | } 28 | }, 29 | "allOf": { 30 | "type": "array", 31 | "items": { 32 | "$ref": "#" 33 | } 34 | }, 35 | "oneOf": { 36 | "type": "array", 37 | "items": { 38 | "$ref": "#" 39 | } 40 | }, 41 | "anyOf": { 42 | "type": "array", 43 | "items": { 44 | "$ref": "#" 45 | } 46 | }, 47 | "contentType": { 48 | "type": "string", 49 | "description": "MIME type of the rendered template output", 50 | "default": "text/plain" 51 | }, 52 | "httpForward": { 53 | "properties": { 54 | "url": { 55 | "oneOf": [ 56 | { "type": "string" }, 57 | { 58 | "type": "object", 59 | "description": "matches Node http.request() options object (https://nodejs.org/api/http.html#http_http_request_options_callback)", 60 | "properties": { 61 | "host": { "type": "string" }, 62 | "path": { "type": "string" } 63 | } 64 | } 65 | ] 66 | } 67 | }, 68 | "required": [ 69 | "url" 70 | ] 71 | } 72 | }, 73 | "required": [ 74 | "template" 75 | ] 76 | } 77 | ] 78 | }, 79 | { 80 | "type": "string", 81 | "format": "mustache" 82 | } 83 | ], 84 | "description": "# templateSchema\n\nProvide a hiearchy of template snippets using mustache style templates.\nthe system will digest and compile the mustache snippets and generate JSON\nschema that represents the input schema to the templates\n\nHTML Templating Example:\n\\`\\`\\`yaml\n view:\n message: Hello!\n definitions:\n body:\n template:\n \n

{{message}}

\n \n template: |\n \n {{> body}}\n \n\\`\\`\\`\n\nA templateSchema object is any object that passes this schema. In short,\nthese objects are valid json schema with a required 'template' property that\ncontains a mustache template.\n\nThe framework mainly acts using the follow three propeties:\n\ntemplate: the base template for this templateSchema object\ndefinitions: a dictionary of other templateSchema objects that can be used\n as partials in the top level template\nview: a view for the template will be rendered with\n\nWhen the system digests the schema, it will parse the template and any\npartials specified in the definitions object, and generate a top level schema\nof properties required to render the template.\n\nThe view object is optional, and can be used to provide an example or defaults\nfor the template.\n\nThe top level schema generated from parsing the mustache template will be used\nto validate the view object. This schema can then be used to validate other\nviews used to render the template.\n" 85 | } 86 | -------------------------------------------------------------------------------- /test/schema_provider.js: -------------------------------------------------------------------------------- 1 | /* Copyright 2021 F5 Networks, Inc. 2 | * 3 | * Licensed under the Apache License, Version 2.0 (the "License"); 4 | * you may not use this file except in compliance with the License. 5 | * You may obtain a copy of the License at 6 | * 7 | * http://www.apache.org/licenses/LICENSE-2.0 8 | * 9 | * Unless required by applicable law or agreed to in writing, software 10 | * distributed under the License is distributed on an "AS IS" BASIS, 11 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | * See the License for the specific language governing permissions and 13 | * limitations under the License. 14 | */ 15 | 16 | /* eslint-disable prefer-arrow-callback */ 17 | /* eslint-disable func-names */ 18 | /* eslint-disable no-console */ 19 | 20 | 'use strict'; 21 | 22 | const fs = require('fs'); 23 | const nock = require('nock'); 24 | const chai = require('chai'); 25 | const chaiAsPromised = require('chai-as-promised'); 26 | 27 | chai.use(chaiAsPromised); 28 | const assert = chai.assert; 29 | 30 | const StorageMemory = require('@f5devcentral/atg-storage').StorageMemory; 31 | const { FsSchemaProvider, DataStoreSchemaProvider } = require('../lib/schema_provider'); 32 | const { GitHubSchemaProvider } = require('../lib/github_provider'); 33 | const { nockGitHubAPI } = require('./githubMock'); 34 | 35 | const schemasPath = './test/templatesets/test/'; 36 | 37 | function runSharedTests(createProvider) { 38 | it('construct', function () { 39 | const provider = createProvider(); 40 | assert.ok(provider); 41 | }); 42 | it('load_single', function () { 43 | const provider = createProvider(); 44 | return provider.fetch('types') 45 | .then(schema => JSON.parse(schema)) 46 | .then((schema) => { 47 | assert.ok(schema); 48 | console.log(JSON.stringify(schema, null, 2)); 49 | assert.ok(schema.definitions.port); 50 | }); 51 | }); 52 | it('load_single_bad', function () { 53 | const provider = createProvider(); 54 | return assert.isRejected(provider.fetch('does_not_exist')); 55 | }); 56 | it('load_list', function () { 57 | const provider = createProvider(); 58 | return assert.becomes(provider.list(), [ 59 | 'types' 60 | ]); 61 | }); 62 | } 63 | 64 | describe('schema provider tests', function () { 65 | describe('FsSchemaProvider', function () { 66 | runSharedTests(() => new FsSchemaProvider(schemasPath)); 67 | it('bad_schema_path', function () { 68 | const provider = new FsSchemaProvider('bad/path'); 69 | return Promise.all([ 70 | assert.isRejected(provider.list()), 71 | assert.isRejected(provider.fetch('f5')) 72 | ]); 73 | }); 74 | 75 | it('schema_path_alias', function () { 76 | const provider = new FsSchemaProvider(schemasPath); 77 | 78 | provider.schema_path = 'foo'; 79 | assert.strictEqual(provider.schemaPath, provider.schema_path); 80 | }); 81 | }); 82 | 83 | describe('DataStoreSchemaProvider', function () { 84 | const createDataStore = () => new StorageMemory({ 85 | test: { 86 | templates: {}, 87 | schemas: fs.readdirSync(`${schemasPath}`).filter(x => x.endsWith('.json')).reduce((acc, fname) => { 88 | acc[fname.slice(0, -5)] = fs.readFileSync(`${schemasPath}/${fname}`, { encoding: 'utf8' }); 89 | return acc; 90 | }, {}) 91 | } 92 | }); 93 | runSharedTests(() => new DataStoreSchemaProvider(createDataStore(), 'test')); 94 | it('bad_ts_name', function () { 95 | const provider = new DataStoreSchemaProvider(createDataStore(), 'does_not_exist'); 96 | return Promise.all([ 97 | assert.isRejected(provider.list()), 98 | assert.isRejected(provider.fetch('f5')) 99 | ]); 100 | }); 101 | }); 102 | 103 | describe('GitHubSchemaProvider', function () { 104 | const repo = 'f5-test/f5-fast-test-templatesets'; 105 | before(() => nockGitHubAPI(repo, './test/templatesets')); 106 | after(() => nock.cleanAll()); 107 | 108 | runSharedTests(() => new GitHubSchemaProvider( 109 | repo, 110 | 'test', 111 | { 112 | apiToken: 'secret' 113 | } 114 | )); 115 | }); 116 | }); 117 | -------------------------------------------------------------------------------- /lib/data_provider.js: -------------------------------------------------------------------------------- 1 | /* Copyright 2021 F5 Networks, Inc. 2 | * 3 | * Licensed under the Apache License, Version 2.0 (the "License"); 4 | * you may not use this file except in compliance with the License. 5 | * You may obtain a copy of the License at 6 | * 7 | * http://www.apache.org/licenses/LICENSE-2.0 8 | * 9 | * Unless required by applicable law or agreed to in writing, software 10 | * distributed under the License is distributed on an "AS IS" BASIS, 11 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | * See the License for the specific language governing permissions and 13 | * limitations under the License. 14 | */ 15 | 16 | 'use strict'; 17 | 18 | const fs = require('fs'); 19 | 20 | const ResourceCache = require('./resource_cache').ResourceCache; 21 | 22 | /** 23 | * Abstract base class for DataProvider classes 24 | */ 25 | class BaseDataProvider { 26 | constructor() { 27 | if (new.target === BaseDataProvider) { 28 | throw new TypeError('Cannot instantiate Abstract BaseDataProvider'); 29 | } 30 | 31 | const abstractMethods = [ 32 | '_loadData', 33 | 'list' 34 | ]; 35 | abstractMethods.forEach((method) => { 36 | if (this[method] === undefined) { 37 | throw new TypeError(`Expected ${method} to be defined`); 38 | } 39 | }); 40 | 41 | this.cache = new ResourceCache(dataName => this._loadData(dataName)); 42 | } 43 | 44 | /** 45 | * Get the data file contents associated with the supplied key 46 | * 47 | * @param {string} key 48 | * @returns {object} 49 | */ 50 | fetch(key) { 51 | return this.cache.fetch(key); 52 | } 53 | } 54 | 55 | /** 56 | * DataProvider that fetches data from the file system 57 | */ 58 | class FsDataProvider extends BaseDataProvider { 59 | /** 60 | * @param {string} dataRootPath - a path to a directory containing data files 61 | */ 62 | constructor(dataRootPath) { 63 | super(); 64 | 65 | this.dataPath = dataRootPath; 66 | } 67 | 68 | _loadData(dataName) { 69 | return new Promise((resolve, reject) => { 70 | fs.readFile(`${this.dataPath}/${dataName}.data`, (err, data) => { 71 | if (err) return reject(err); 72 | return resolve(data.toString('utf8')); 73 | }); 74 | }); 75 | } 76 | 77 | /** 78 | * List all data files known to the provider 79 | * 80 | * @returns {string[]} 81 | */ 82 | list() { 83 | return new Promise((resolve, reject) => { 84 | fs.readdir(this.dataPath, (err, data) => { 85 | if (err) return reject(err); 86 | 87 | const list = data.filter(x => x.endsWith('.data')) 88 | .map(x => x.replace(/.data$/, '')); 89 | return resolve(list); 90 | }); 91 | }); 92 | } 93 | } 94 | 95 | /** 96 | * DataProvider that fetches data from an atg-storage DataStore 97 | */ 98 | class DataStoreDataProvider extends BaseDataProvider { 99 | /** 100 | * @param {object} datastore - an atg-storage DataStore 101 | * @param {string} tsName - the key to use to access the data file contents in the provided DataStore 102 | */ 103 | constructor(datastore, tsName) { 104 | super(); 105 | 106 | this.storage = datastore; 107 | this.tsName = tsName; 108 | } 109 | 110 | _loadData(dataName) { 111 | return this.storage.hasItem(this.tsName) 112 | .then((result) => { 113 | if (result) { 114 | return Promise.resolve(); 115 | } 116 | return Promise.reject(new Error(`Could not find template set "${this.tsName}" in data store`)); 117 | }) 118 | .then(() => this.storage.getItem(this.tsName)) 119 | .then(ts => ts.dataFiles[dataName]) 120 | .then((data) => { 121 | if (typeof data === 'undefined') { 122 | return Promise.reject(new Error(`Failed to find data file named "${dataName}"`)); 123 | } 124 | return Promise.resolve(data); 125 | }); 126 | } 127 | 128 | /** 129 | * List all data files known to the provider 130 | * 131 | * @returns {string[]} 132 | */ 133 | list() { 134 | return this.storage.hasItem(this.tsName) 135 | .then((result) => { 136 | if (result) { 137 | return Promise.resolve(); 138 | } 139 | return Promise.reject(new Error(`Could not find template set "${this.tsName}" in data store`)); 140 | }) 141 | .then(() => this.storage.getItem(this.tsName)) 142 | .then(ts => Object.keys(ts.dataFiles)); 143 | } 144 | } 145 | 146 | module.exports = { 147 | BaseDataProvider, 148 | FsDataProvider, 149 | DataStoreDataProvider 150 | }; 151 | -------------------------------------------------------------------------------- /lib/schema_provider.js: -------------------------------------------------------------------------------- 1 | /* Copyright 2021 F5 Networks, Inc. 2 | * 3 | * Licensed under the Apache License, Version 2.0 (the "License"); 4 | * you may not use this file except in compliance with the License. 5 | * You may obtain a copy of the License at 6 | * 7 | * http://www.apache.org/licenses/LICENSE-2.0 8 | * 9 | * Unless required by applicable law or agreed to in writing, software 10 | * distributed under the License is distributed on an "AS IS" BASIS, 11 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | * See the License for the specific language governing permissions and 13 | * limitations under the License. 14 | */ 15 | 16 | 'use strict'; 17 | 18 | const fs = require('fs'); 19 | 20 | const ResourceCache = require('./resource_cache').ResourceCache; 21 | 22 | /** 23 | * Abstract base class for SchemaProvider classes 24 | */ 25 | class BaseSchemaProvider { 26 | constructor() { 27 | if (new.target === BaseSchemaProvider) { 28 | throw new TypeError('Cannot instantiate Abstract BaseSchemaProvider'); 29 | } 30 | 31 | const abstractMethods = [ 32 | '_loadSchema', 33 | 'list' 34 | ]; 35 | abstractMethods.forEach((method) => { 36 | if (this[method] === undefined) { 37 | throw new TypeError(`Expected ${method} to be defined`); 38 | } 39 | }); 40 | 41 | this.cache = new ResourceCache(schemaName => this._loadSchema(schemaName)); 42 | } 43 | 44 | /** 45 | * Get the schema associated with the supplied key 46 | * 47 | * @param {string} key 48 | * @returns {object} 49 | */ 50 | fetch(key) { 51 | return this.cache.fetch(key); 52 | } 53 | } 54 | 55 | /** 56 | * SchemaProvider that fetches data from the file system 57 | */ 58 | class FsSchemaProvider extends BaseSchemaProvider { 59 | /** 60 | * @param {string} schemaRootPath - a path to a directory containing schema files 61 | */ 62 | constructor(schemaRootPath) { 63 | super(); 64 | 65 | this.schemaPath = schemaRootPath; 66 | } 67 | 68 | get schema_path() { 69 | return this.schemaPath; 70 | } 71 | 72 | set schema_path(value) { 73 | this.schemaPath = value; 74 | } 75 | 76 | _loadSchema(schemaName) { 77 | return new Promise((resolve, reject) => { 78 | fs.readFile(`${this.schemaPath}/${schemaName}.json`, (err, data) => { 79 | if (err) return reject(err); 80 | return resolve(data.toString('utf8')); 81 | }); 82 | }); 83 | } 84 | 85 | /** 86 | * List all schema known to the provider 87 | * 88 | * @returns {string[]} 89 | */ 90 | list() { 91 | return new Promise((resolve, reject) => { 92 | fs.readdir(this.schemaPath, (err, data) => { 93 | if (err) return reject(err); 94 | 95 | const list = data.filter(x => x.endsWith('.json')) 96 | .map(x => x.replace(/.json$/, '')); 97 | return resolve(list); 98 | }); 99 | }); 100 | } 101 | } 102 | 103 | /** 104 | * SchemaProvider that fetches data from an atg-storage DataStore 105 | */ 106 | class DataStoreSchemaProvider extends BaseSchemaProvider { 107 | /** 108 | * @param {object} datastore - an atg-storage DataStore 109 | * @param {string} tsName - the key to use to access the schema in the provided DataStore 110 | */ 111 | constructor(datastore, tsName) { 112 | super(); 113 | 114 | this.storage = datastore; 115 | this.tsName = tsName; 116 | } 117 | 118 | _loadSchema(schemaName) { 119 | return this.storage.hasItem(this.tsName) 120 | .then((result) => { 121 | if (result) { 122 | return Promise.resolve(); 123 | } 124 | return Promise.reject(new Error(`Could not find template set "${this.tsName}" in data store`)); 125 | }) 126 | .then(() => this.storage.getItem(this.tsName)) 127 | .then(ts => ts.schemas[schemaName]) 128 | .then((schema) => { 129 | if (typeof schema === 'undefined') { 130 | return Promise.reject(new Error(`Failed to find schema named "${schemaName}"`)); 131 | } 132 | return Promise.resolve(schema); 133 | }); 134 | } 135 | 136 | /** 137 | * List all schema known to the provider 138 | * 139 | * @returns {string[]} 140 | */ 141 | list() { 142 | return this.storage.hasItem(this.tsName) 143 | .then((result) => { 144 | if (result) { 145 | return Promise.resolve(); 146 | } 147 | return Promise.reject(new Error(`Could not find template set "${this.tsName}" in data store`)); 148 | }) 149 | .then(() => this.storage.getItem(this.tsName)) 150 | .then(ts => Object.keys(ts.schemas)); 151 | } 152 | } 153 | 154 | module.exports = { 155 | BaseSchemaProvider, 156 | FsSchemaProvider, 157 | DataStoreSchemaProvider 158 | }; 159 | -------------------------------------------------------------------------------- /test/transaction_logger.js: -------------------------------------------------------------------------------- 1 | /* Copyright 2021 F5 Networks, Inc. 2 | * 3 | * Licensed under the Apache License, Version 2.0 (the "License"); 4 | * you may not use this file except in compliance with the License. 5 | * You may obtain a copy of the License at 6 | * 7 | * http://www.apache.org/licenses/LICENSE-2.0 8 | * 9 | * Unless required by applicable law or agreed to in writing, software 10 | * distributed under the License is distributed on an "AS IS" BASIS, 11 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | * See the License for the specific language governing permissions and 13 | * limitations under the License. 14 | */ 15 | 16 | /* eslint-disable prefer-arrow-callback */ 17 | /* eslint-disable func-names */ 18 | /* eslint-disable no-console */ 19 | 20 | 'use strict'; 21 | 22 | const assert = require('assert'); 23 | 24 | const TransactionLogger = require('../lib/transaction_logger'); 25 | 26 | describe('TransactionLogger', function () { 27 | describe('Init', function () { 28 | it('should provide default callbacks', function () { 29 | const tl = new TransactionLogger(); 30 | assert.ok(tl.onEnterCb); 31 | assert.ok(tl.onExitCb); 32 | }); 33 | }); 34 | 35 | describe('Enter', function () { 36 | it('should error on missing transaction', function () { 37 | const tl = new TransactionLogger(); 38 | assert.throws(tl.enter, /transaction/); 39 | }); 40 | it('should store transaction', function () { 41 | const tl = new TransactionLogger(); 42 | tl.enter('a'); 43 | assert.ok(tl.transactions['a-0']); 44 | }); 45 | it('should call onEnter callback', function () { 46 | let called = false; 47 | const tl = new TransactionLogger( 48 | (transaction, enterTime) => { 49 | called = true; 50 | assert.strictEqual(transaction, 'a transaction'); 51 | assert.ok(enterTime); 52 | } 53 | ); 54 | tl.enter('a transaction'); 55 | assert(called, 'expected onEnter to be called'); 56 | }); 57 | }); 58 | 59 | describe('Exit', function () { 60 | it('should error on missing transaction', function () { 61 | const tl = new TransactionLogger(); 62 | assert.throws(tl.exit, /transaction/); 63 | }); 64 | it('should error if called without enter()', function () { 65 | const tl = new TransactionLogger(); 66 | assert.throws(() => tl.exit('a'), /called without enter/); 67 | }); 68 | it('should call onExit callback', function () { 69 | let called = false; 70 | const tl = new TransactionLogger( 71 | () => {}, 72 | (transaction, exitTime, deltaTime) => { 73 | called = true; 74 | assert.strictEqual(transaction, 'a transaction'); 75 | assert.ok(exitTime); 76 | assert.notStrictEqual(typeof deltaTime, 'undefined'); 77 | } 78 | ); 79 | tl.enter('a transaction'); 80 | tl.exit('a transaction'); 81 | assert(called, 'expected onExit to be called'); 82 | }); 83 | }); 84 | 85 | describe('Record Promise', function () { 86 | it('should error on missing transaction', function () { 87 | const tl = new TransactionLogger(); 88 | assert.throws(tl.exit, /transaction/); 89 | }); 90 | it('should call onEnter() and onExit()', function () { 91 | let onEnterCalled = false; 92 | let onExitCalled = false; 93 | const tl = new TransactionLogger( 94 | (transaction, enterTime) => { 95 | onEnterCalled = true; 96 | assert.strictEqual(transaction, 'a transaction'); 97 | assert.ok(enterTime); 98 | }, 99 | (transaction, exitTime, deltaTime) => { 100 | onExitCalled = true; 101 | assert.strictEqual(transaction, 'a transaction'); 102 | assert.ok(exitTime); 103 | assert(typeof deltaTime !== 'undefined'); 104 | } 105 | ); 106 | return Promise.resolve() 107 | .then(() => tl.enterPromise('a transaction', Promise.resolve())) 108 | .then(() => { 109 | assert(onEnterCalled, 'expected onEnter to be called'); 110 | assert(onExitCalled, 'expected onExit to be called'); 111 | }); 112 | }); 113 | it('should call onExit() on a rejected promise', function () { 114 | let called = false; 115 | const tl = new TransactionLogger( 116 | () => {}, 117 | (transaction, exitTime, deltaTime) => { 118 | called = true; 119 | assert.strictEqual(transaction, 'a transaction'); 120 | assert.ok(exitTime); 121 | assert(typeof deltaTime !== 'undefined'); 122 | } 123 | ); 124 | return Promise.resolve() 125 | .then(() => tl.enterPromise('a transaction', Promise.reject())) 126 | .then(() => { 127 | assert(called, 'expected onExit to be called'); 128 | }) 129 | .catch(() => {}); 130 | }); 131 | }); 132 | }); 133 | -------------------------------------------------------------------------------- /scripts/auditProcessor.js: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env node 2 | /* 3 | * Copyright 2021. F5 Networks, Inc. See End User License Agreement ("EULA") for 4 | * license terms. Notwithstanding anything to the contrary in the EULA, Licensee 5 | * may copy and modify this software product for its internal business purposes. 6 | * Further, Licensee may upload, publish and distribute the modified version of 7 | * the software product on devcentral.f5.com. 8 | * 9 | * Usage: node auditProcessor.js --help 10 | */ 11 | 12 | 'use strict'; 13 | 14 | const fs = require('fs'); 15 | const path = require('path'); 16 | const yargs = require('yargs'); 17 | 18 | const PACKAGE_JSON = path.join(process.cwd(), 'package.json'); 19 | const AUDIT_REPORT = path.join(process.cwd(), '.auditReport.json'); 20 | const DEFAULT_EXIT_CODE = 0; 21 | 22 | class AuditProcessor { 23 | constructor() { 24 | this.report = {}; 25 | this.vulnerabilities = []; 26 | this.exitCode = DEFAULT_EXIT_CODE; 27 | } 28 | 29 | log(msg) { 30 | console.log(msg); // eslint-disable-line no-console 31 | } 32 | 33 | /** 34 | * Load report - Loads "npm audit --json" output 35 | * 36 | * @returns {Void} 37 | */ 38 | loadReport() { 39 | if (!fs.existsSync(AUDIT_REPORT)) { 40 | throw new Error('Please run "npm audit" first.'); 41 | } 42 | this.report = JSON.parse(fs.readFileSync(AUDIT_REPORT, 'utf-8')); 43 | } 44 | 45 | /** 46 | * Process report 47 | * 48 | * @param {Object} options - function options 49 | * @param {Array} [options.allowlist] - array containing zero or more ID's to ignore 50 | * 51 | * @returns {Void} 52 | */ 53 | processReport(options) { 54 | options = options || {}; 55 | const allowlist = options.allowlist || []; 56 | 57 | // parse out vulnerabilities 58 | if (this.report.auditReportVersion === 2) { 59 | Object.keys(this.report.vulnerabilities).forEach((key) => { 60 | this.report.vulnerabilities = this._resolveVia(this.report.vulnerabilities, key); 61 | this.vulnerabilities.push({ 62 | module: key, 63 | path: this.report.vulnerabilities[key].nodes[0], 64 | vulnerability: { 65 | id: this.report.vulnerabilities[key].via[0].source, 66 | url: this.report.vulnerabilities[key].via[0].url, 67 | advisory: this.report.vulnerabilities[key].via[0].url.split('/').slice(-1)[0], 68 | recommendation: null 69 | } 70 | }); 71 | }); 72 | } else { 73 | this.report.actions.forEach((action) => { 74 | action.resolves.forEach((item) => { 75 | this.vulnerabilities.push({ 76 | module: action.module, 77 | path: item.path, 78 | vulnerability: { 79 | id: item.id, 80 | url: this.report.advisories[item.id].url, 81 | advisory: this.report.advisories[item.id].url.split('/').slice(-1)[0], 82 | recommendation: this.report.advisories[item.id].recommendation 83 | } 84 | }); 85 | }); 86 | }); 87 | } 88 | // determine if any vulnerabilities should be ignored 89 | if (allowlist.length) { 90 | this.vulnerabilities = this.vulnerabilities.filter( 91 | vuln => !allowlist.includes(vuln.vulnerability.id) && !allowlist.includes(vuln.vulnerability.advisory) 92 | ); 93 | } 94 | } 95 | 96 | /** 97 | * Notify - Determine exit code, what should be logged 98 | * 99 | * @returns {Void} 100 | */ 101 | notify() { 102 | // check for vulnerabilities and act accordingly 103 | if (this.vulnerabilities.length) { 104 | this.log(this.vulnerabilities); 105 | this.log(`IMPORTANT: ${this.vulnerabilities.length} vulnerabilities exist, please resolve them!`); 106 | process.exit(1); 107 | } 108 | // good to go 109 | this.log('No package dependency vulnerabilities exist!'); 110 | process.exit(this.exitCode); 111 | } 112 | 113 | _resolveVia(vulnerabilities, key) { 114 | while (typeof vulnerabilities[key].via[0] === 'string') { 115 | let count = 0; 116 | if (vulnerabilities[key].via[0] === vulnerabilities[vulnerabilities[key].via[0]].via[0]) { 117 | count += 1; 118 | } 119 | vulnerabilities[key].via[0] = vulnerabilities[vulnerabilities[key].via[0]].via[count]; 120 | } 121 | return vulnerabilities; 122 | } 123 | } 124 | 125 | function main() { 126 | const argv = yargs 127 | .version('1.0.0') 128 | .command('allowlist', 'Allow specific vulnerabilities by ID') 129 | .example('$0 --allowlist 1234,1235', 'Allow vulnerabilities 1234 and 1235') 130 | .help('help') 131 | .argv; 132 | 133 | const optionsFromConfig = JSON.parse(fs.readFileSync(PACKAGE_JSON, 'utf-8')).auditProcessor || {}; 134 | const parsedArgs = { 135 | allowlist: argv.allowlist || optionsFromConfig.allowlist || '' 136 | }; 137 | 138 | const auditProcessor = new AuditProcessor(); 139 | auditProcessor.loadReport(); 140 | auditProcessor.processReport({ 141 | allowlist: parsedArgs.allowlist.toString().split(',').map(item => parseInt(item, 10) || item) 142 | }); 143 | auditProcessor.notify(); 144 | } 145 | 146 | main(); 147 | -------------------------------------------------------------------------------- /docs/templating.md: -------------------------------------------------------------------------------- 1 | # Templating with F5 BIG-IP FAST 2 | 3 | BIG-IP FAST leverages existing, familiar technologies such as Mustache and JSON Schema to provide a complete templating solution that supports comprehensive parameter validation. 4 | Template text is written in [Mustache](https://mustache.github.io/mustache.5.html). 5 | That template text is then parsed to extract any parameters and provide basic JSON Schema for them. 6 | Users can write their own JSON Schema for each parameter to expand on the basic schema that is auto-generated by BIG-IP FAST. 7 | When rendering templates, this combined schema is then used to validate any inputs (parameters) to the template. 8 | 9 | ## Mustache 10 | Mustache is not the templating engine. 11 | Mustache is a specification for a templating language, and it specifies how the template file must look. 12 | You write templates adhering to the Mustache specification, and it works by expanding tags in a template using values provided in a hash or object. 13 | The template is then rendered to create an output. 14 | 15 | [Here](getting_started.md#cli) is a simple example of rendering a template with the FAST CLI. 16 | 17 | ## Tags 18 | Variables are expanded in a FAST template with the various [Mustache Tag Types](https://mustache.github.io/mustache.5.html#TAG-TYPES) -- which are easily identified by the double mustache of opening and closing curley braces {{ }}. 19 | 20 | A {{tenant}} tag in a template renders the value of the tenant parameter definition. 21 | 22 | Template: 23 | ```yaml 24 | definitions: 25 | template: 26 | type: string 27 | default: Tenant_1 28 | application_name: 29 | type: string 30 | default: App_1 31 | template: | 32 | { 33 | "{{tenant}}": { 34 | "class": "Tenant", 35 | "{{application_name}}": { 36 | "class": "Application" 37 | } 38 | } 39 | } 40 | ``` 41 | 42 | Parameters: 43 | ```yaml 44 | { 45 | "tenant": "Tenant_2", 46 | "application_name": "App_2" 47 | } 48 | ``` 49 | 50 | Outputs: 51 | ```javascript 52 | { 53 | "Tenant_2": { 54 | "class": "Tenant", 55 | "App_2": { 56 | "class": "Application" 57 | } 58 | } 59 | } 60 | ``` 61 | 62 | ## Sections 63 | For iterating over a list of data, we make use of [Mustache Sections](https://mustache.github.io/mustache.5.html#Sections). 64 | The behavior of the section is determined by the value of the key. 65 | Two types of lists can be created: Empty List or Non-Empty List. 66 | 67 | ### False Values or Empty Lists 68 | 69 | If the parameter defition exists, and has a value of false, or an empty list, it will not be displayed. 70 | In the following example, the members' property definition has false assigned to it, so it will not be displayed. 71 | Instead, the message indicating that members is missing or false will display in the [Inverted Section](https://mustache.github.io/mustache.5.html#Inverted-Sections). 72 | 73 | Template: 74 | ```yaml 75 | template: | 76 | Members: 77 | {{#members}} 78 | "{{ . }}", 79 | {{/members}} 80 | {{^members}} 81 | "No members exist." 82 | {{/members}} 83 | ``` 84 | 85 | Parameters: 86 | ```yaml 87 | members: false 88 | ``` 89 | 90 | Output: 91 | ``` 92 | Members: 93 | No members exist. 94 | ``` 95 | 96 | ### Non-Empty Lists 97 | When the members definition has a value that is a [Non-Empty Mustache List](https://mustache.github.io/mustache.5.html#Sections), the text in the block will be displayed once for each item in the list. 98 | The context of the block will be set to the current item for each iteration. 99 | The template in the previous example will loop over a collection of members, with the following parameter definition and output. 100 | 101 | Parameters: 102 | ```yaml 103 | members: 104 | - 10.0.0.1 105 | - 10.0.0.2 106 | - 10.0.0.3 107 | ``` 108 | 109 | Output: 110 | ``` 111 | Members: 112 | 10.0.0.1, 113 | 10.0.0.2, 114 | 10.0.0.3, 115 | ``` 116 | 117 | 118 | ## Partials 119 | Along with sections, Mustache utilizes partials. 120 | Mustache partials can be thought of as a way to insert template snippets. 121 | The syntax for including a partial uses curley braces and an angle bracket {{> }}. 122 | 123 | For BIG-IP FAST, a partial definition must contain template text, i.e., define a template property 124 | ```yaml 125 | definitions: 126 | partialDef: 127 | template: | 128 | {{#useVar}} 129 | {{var}} 130 | {{/useVar}} 131 | useVar: 132 | type: boolean 133 | template: | 134 | {{> partialDef}} 135 | {{> partialDef}} 136 | ``` 137 | 138 | Parameters: 139 | ```yaml 140 | { 141 | "useVar": true, 142 | "var": "sample" 143 | } 144 | ``` 145 | 146 | Outputs: 147 | ```yaml 148 | sample 149 | sample 150 | ``` 151 | 152 | > **See Also:** [Mustache Manual](https://mustache.github.io/mustache.5.html) for more information on Partials. 153 | 154 | 155 | # Template Data Files 156 | 157 | Sometimes it is desirable to keep a portion of a template in a separate file and include it into the template text. 158 | This can be done with parameters and the `dataFile` property: 159 | 160 | ```javascript 161 | const fast = require('@f5devcentral/f5-fast-core'); 162 | 163 | const templatesPath = '/path/to/templatesdir'; // directory containing example.data 164 | const dataProvider = new fast.FsDataProvider(templatesPath); 165 | const yamldata = ` 166 | definitions: 167 | var: 168 | dataFile: example 169 | template: | 170 | {{var}} 171 | `; 172 | 173 | fast.Template.loadYaml(yamldata, { dataProvider }) 174 | .then((template) => { 175 | console.log(template.getParametersSchema()); 176 | console.log(template.render({virtual_port: 443}); 177 | }); 178 | ``` 179 | The `FsDataProvider` will pick up on any files with the `.data` extension in the template set directory. 180 | When referencing the file in a template, use the filename (without the extension) as a key. 181 | 182 | Parameters with a `dataFile` property: 183 | 184 | * are removed from `required` 185 | * have their `default` set to the contents of the file 186 | * given a default `format` of `hidden` 187 | 188 | Additionally, the contents of the data file can be base64-encoded before being used as for `default` by setting the `toBase64` property to `true`: 189 | 190 | ```yaml 191 | definitions: 192 | var: 193 | dataFile: example 194 | toBase64: true 195 | template: | 196 | {{var}} 197 | ``` 198 | 199 | Similarly, if the data file is base64-encoded, it can be decoded using `fromBase64`. 200 | If both `toBase64` and `fromBase64` are set, then `toBase64` takes precedence. 201 | 202 | > **See Also:** [AS3 Schema Reference](https://clouddocs.f5.com/products/extensions/f5-appsvcs-extension/latest/refguide/schema-reference.html) for a full list of f5base64 fields. 203 | -------------------------------------------------------------------------------- /docs/api.md: -------------------------------------------------------------------------------- 1 | # Module API 2 | 3 | ## Simple Loading 4 | 5 | Below is a basic example for loading a template without any additional type schema: 6 | 7 | ```javascript 8 | const fast = require('@f5devcentral/f5-fast-core'); 9 | 10 | const yamldata = ` 11 | parameters: 12 | message: Hello! 13 | definitions: 14 | body: 15 | template: 16 | 17 |

{{message}}

18 | 19 | template: | 20 | 21 | {{> body}} 22 | 23 | `; 24 | 25 | fast.Template.loadYaml(yamldata) 26 | .then((template) => { 27 | console.log(template.getParametersSchema()); 28 | console.log(template.render({message: "Hello world!"})); 29 | }); 30 | ``` 31 | 32 | > **Note:** If the example above were saved in a file named simpleLoading.js, then you could run it from the CLI with this command: `node simpleLoading.js` 33 | 34 | If a `Template` has been serialized to JSON (e.g., to send in an HTTP request), it can be deserialized with `Template.fromJson()`: 35 | 36 | ```javascript 37 | const fast = require('@f5devcentral/f5-fast-core'); 38 | 39 | const yamldata = ` 40 | template: | 41 | {{message}} 42 | `; 43 | 44 | fast.Template.loadYaml(yamldata) 45 | .then(template => JSON.stringify(template)) 46 | .then(jsonData => template.fromJson(jsonData)) 47 | .then((template) => { 48 | console.log(template.getParametersSchema()); 49 | console.log(template.render({message: "Hello world!"})); 50 | }); 51 | ``` 52 | 53 | `Template` does not provide a mechanism for loading a template from a file and, instead, needs to be paired with something like Node's `fs` module: 54 | 55 | ```javascript 56 | const fs = require('fs'); 57 | const fast = require('@f5devcentral/f5-fast-core'); 58 | 59 | const yamldata = fs.readFileSync('path/to/file', 'utf8'); 60 | 61 | fast.Template.loadYaml(yamldata) 62 | .then((template) => { 63 | console.log(template.getParametersSchema()); 64 | console.log(template.render({message: "Hello world!"})); 65 | }); 66 | ``` 67 | 68 | ## Loading with Type Schema 69 | 70 | To support user-defined types, a `SchemaProvider` must be used. 71 | The `FsSchemaProvider` can be used to load schema from disk: 72 | 73 | ```javascript 74 | const fast = require('@f5devcentral/f5-fast-core'); 75 | 76 | const templatesPath = '/path/to/templatesdir'; // directory containing types.json 77 | const schemaProvider = new fast.FsSchemaProvider(templatesPath); 78 | const yamldata = ` 79 | template: | 80 | {{virtual_port:types:port}} 81 | `; 82 | 83 | fast.Template.loadYaml(yamldata, schemaProvider) 84 | .then((template) => { 85 | console.log(template.getParametersSchema()); 86 | console.log(template.render({virtual_port: 443}); 87 | }); 88 | ``` 89 | 90 | 91 | ## Using a TemplateProvider 92 | 93 | A higher-level API is available for loading templates via `TemplateProvider` classes. 94 | These classes will handle calling the correct load function (`Template.loadYaml()` vs `Template.loadMst()`) and can also automatically handle additional schema files. 95 | For example, to load "templates sets" (a directory containing template files) from a given directory, the `FsTemplateProvider` class can be used: 96 | 97 | ```javascript 98 | const fast = require('@f5devcentral/f5-fast-core'); 99 | 100 | const templateSetsPath = '/path/to/templateSetsDir'; 101 | const templateProvider = new fast.FsTemplateProvider(templateSetsPath); 102 | 103 | templateProvider.fetch('templateSetName/templateName') 104 | .then((template) => { 105 | console.log(template.getParametersSchema()); 106 | console.log(template.render({ 107 | var: "value", 108 | boolVar: false 109 | })); 110 | }); 111 | ``` 112 | 113 | If only a subset of the directories should be loaded as template sets, `FsTemplateProvider` provides an option to filter directories: 114 | 115 | ```javascript 116 | const fast = require('@f5devcentral/f5-fast-core'); 117 | 118 | const templateSetsPath = '/path/to/templateSetsDir'; 119 | const setsToLoad = ['foo', 'bar']; 120 | const templateProvider = new fast.FsTemplateProvider(templateSetsPath, setsToLoad); 121 | 122 | templateProvider.fetch('templateSetName/templateName') 123 | .then((template) => { 124 | console.log(template.getParametersSchema()); 125 | console.log(template.render({ 126 | var: "value", 127 | boolVar: false 128 | })); 129 | }); 130 | ``` 131 | 132 | A `FsSingleTemplateProvider` is provided as convenience for loading a single template set (instead of a directory of template sets): 133 | 134 | ```javascript 135 | const fast = require('@f5devcentral/f5-fast-core'); 136 | 137 | const templateSetPath = '/path/to/templateSet'; 138 | const templateProvider = new fast.FsSingleTemplateProvider(templateSetPath); 139 | 140 | templateProvider.fetch('templateSet/templateName') 141 | .then((template) => { 142 | console.log(template.getParametersSchema()); 143 | console.log(template.render({ 144 | var: "value", 145 | boolVar: false 146 | })); 147 | }); 148 | ``` 149 | 150 | > **Note:** Despite loading a single template set, a template set name must still be provided when querying the provider. 151 | 152 | 153 | ## Template Data Files 154 | 155 | Sometimes it is desirable to keep a portion of a template in a separate file and include it into the template text. 156 | This can be done with parameters and the `dataFile` property: 157 | 158 | ```javascript 159 | const fast = require('@f5devcentral/f5-fast-core'); 160 | 161 | const templatesPath = '/path/to/templatesdir'; // directory containing example.data 162 | const dataProvider = new fast.FsDataProvider(templatesPath); 163 | const yamldata = ` 164 | definitions: 165 | var: 166 | dataFile: example 167 | template: | 168 | {{var}} 169 | `; 170 | 171 | fast.Template.loadYaml(yamldata, { dataProvider }) 172 | .then((template) => { 173 | console.log(template.getParametersSchema()); 174 | console.log(template.render({virtual_port: 443}); 175 | }); 176 | ``` 177 | The `FsDataProvider` will pick up on any files with the `.data` extension in the template set directory. 178 | When referencing the file in a template, use the filename (without the extension) as a key. 179 | 180 | Parameters with a `dataFile` property: 181 | 182 | * are removed from `required` 183 | * have their `default` set to the contents of the file 184 | * given a default `format` of `hidden` 185 | 186 | Additionally, the contents of the data file can be base64-encoded before being used as for `default` by setting the `toBase64` property to `true`: 187 | 188 | ```yaml 189 | definitions: 190 | var: 191 | dataFile: example 192 | toBase64: true 193 | template: | 194 | {{var}} 195 | ``` 196 | 197 | Similarly, if the data file is base64-encoded, it can be decoded using `fromBase64`. 198 | If both `toBase64` and `fromBase64` are set, then `toBase64` takes precedence. 199 | -------------------------------------------------------------------------------- /lib/gui_utils.js: -------------------------------------------------------------------------------- 1 | /* Copyright 2021 F5 Networks, Inc. 2 | * 3 | * Licensed under the Apache License, Version 2.0 (the "License"); 4 | * you may not use this file except in compliance with the License. 5 | * You may obtain a copy of the License at 6 | * 7 | * http://www.apache.org/licenses/LICENSE-2.0 8 | * 9 | * Unless required by applicable law or agreed to in writing, software 10 | * distributed under the License is distributed on an "AS IS" BASIS, 11 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | * See the License for the specific language governing permissions and 13 | * limitations under the License. 14 | */ 15 | 16 | 'use strict'; 17 | 18 | const Mustache = require('mustache'); 19 | const mergeWith = require('merge-lite'); 20 | 21 | const htmlStub = require('./html_stub'); 22 | 23 | // Disable HTML escaping 24 | Mustache.escape = function escape(text) { 25 | return text; 26 | }; 27 | 28 | const injectFormatsIntoSchema = (schema) => { 29 | Object.values(schema).forEach((item) => { 30 | if (item !== null && typeof item === 'object') { 31 | if (item.type === 'boolean') { 32 | item.format = 'checkbox'; 33 | } else if (item.type === 'array') { 34 | if (item.uniqueItems && item.items && item.items.enum) { 35 | item.format = 'select'; 36 | } else { 37 | item.format = 'table'; 38 | } 39 | } else if (item.format === 'text') { 40 | item.format = 'textarea'; 41 | } 42 | 43 | injectFormatsIntoSchema(item); 44 | } 45 | }); 46 | }; 47 | 48 | const addDepsToSchema = (schema) => { 49 | if (schema.dependencies) { 50 | Object.keys(schema.dependencies).forEach((key) => { 51 | if (!schema.properties[key]) { 52 | return; 53 | } 54 | const depsOpt = schema.dependencies[key].reduce((acc, curr) => { 55 | acc[curr] = !( 56 | schema.properties[key].invertDependency 57 | && schema.properties[key].invertDependency.includes(curr) 58 | ); 59 | return acc; 60 | }, {}); 61 | schema.properties[key].options = Object.assign({}, schema.properties[key].options, { 62 | dependencies: depsOpt 63 | }); 64 | }); 65 | } 66 | if (schema.properties) { 67 | Object.values(schema.properties).forEach((item) => { 68 | addDepsToSchema(item); 69 | delete item.invertDependency; 70 | }); 71 | } 72 | }; 73 | 74 | const keyInXOf = (key, schema) => { 75 | let found = false; 76 | ['oneOf', 'allOf', 'anyOf'].forEach((xOf) => { 77 | if (!schema[xOf]) { 78 | return; 79 | } 80 | schema[xOf].forEach((subSchema) => { 81 | if (subSchema.properties && subSchema.properties[key] !== undefined) { 82 | found = true; 83 | return; 84 | } 85 | found = keyInXOf(key, subSchema) || found; 86 | }); 87 | }); 88 | 89 | return found; 90 | }; 91 | 92 | const fixAllOfOrder = (schema, orderID) => { 93 | orderID = orderID || 0; 94 | 95 | if (schema.allOf) { 96 | schema.allOf.forEach((subSchema) => { 97 | orderID = fixAllOfOrder(subSchema, orderID); 98 | }); 99 | } 100 | 101 | if (schema.properties) { 102 | Object.keys(schema.properties).forEach((key) => { 103 | const prop = schema.properties[key]; 104 | if (!prop.propertyOrder && !keyInXOf(key, schema)) { 105 | prop.propertyOrder = orderID; 106 | orderID += 1; 107 | } 108 | }); 109 | } 110 | 111 | return orderID; 112 | }; 113 | 114 | const mergeAllOf = (schema) => { 115 | const useObjValue = [ 116 | 'title', 117 | 'description', 118 | 'default', 119 | 'propertyOrder' 120 | ]; 121 | 122 | if (!schema.allOf) { 123 | return schema; 124 | } 125 | 126 | schema.allOf.forEach(subSchema => mergeAllOf(subSchema)); 127 | 128 | mergeWith(schema, ...schema.allOf, (objValue, srcValue, key) => { 129 | if (useObjValue.includes(key)) { 130 | return objValue; 131 | } 132 | 133 | if (key === 'required') { 134 | return Array.from(new Set([...(objValue || []), ...srcValue])); 135 | } 136 | 137 | if (key === 'dependencies') { 138 | return mergeWith({}, objValue, srcValue, (dst, src) => { 139 | if (Array.isArray(dst) && Array.isArray(src)) { 140 | return [].concat(dst, src); 141 | } 142 | return undefined; 143 | }); 144 | } 145 | 146 | return undefined; 147 | }); 148 | 149 | delete schema.allOf; 150 | 151 | return schema; 152 | }; 153 | 154 | const collapseAllOf = (schema) => { 155 | fixAllOfOrder(schema); 156 | return mergeAllOf(schema); 157 | }; 158 | 159 | const mergeMixins = (schema) => { 160 | // No anyOf, nothing to do 161 | if (!schema.anyOf) { 162 | return schema; 163 | } 164 | 165 | // Check to see if an item is empty, which implies mixins 166 | let isMixins = false; 167 | schema.anyOf.forEach((item) => { 168 | if (Object.keys(item).length === 0) { 169 | isMixins = true; 170 | } else if (item.type && item.type === 'object' 171 | && item.properties && Object.keys(item.properties).length === 0) { 172 | isMixins = true; 173 | } 174 | }); 175 | if (!isMixins) { 176 | return schema; 177 | } 178 | 179 | // Merge mixins, but do not make them required 180 | schema.anyOf.forEach((item) => { 181 | item = mergeMixins(item); 182 | mergeWith(schema.properties, item.properties || {}); 183 | mergeWith(schema.dependencies, item.dependencies || {}); 184 | }); 185 | delete schema.anyOf; 186 | 187 | return schema; 188 | }; 189 | 190 | const removeMathExpressions = (schema) => { 191 | if (!schema.properties) { 192 | return schema; 193 | } 194 | 195 | schema.properties = Object.keys(schema.properties).reduce((acc, curr) => { 196 | const prop = schema.properties[curr]; 197 | const remove = ( 198 | typeof prop.mathExpression !== 'undefined' 199 | && prop.format && prop.format === 'hidden' 200 | && !prop.title 201 | && !prop.description 202 | ); 203 | if (!remove) { 204 | acc[curr] = prop; 205 | } 206 | return acc; 207 | }, {}); 208 | 209 | return schema; 210 | }; 211 | 212 | const modSchemaForJSONEditor = (schema) => { 213 | schema = JSON.parse(JSON.stringify(schema)); // Do not modify original schema 214 | schema.title = schema.title || 'Template'; 215 | schema = collapseAllOf(schema); 216 | injectFormatsIntoSchema(schema); 217 | schema = mergeMixins(schema); 218 | addDepsToSchema(schema); 219 | schema = removeMathExpressions(schema); 220 | 221 | return schema; 222 | }; 223 | 224 | const filterExtraProperties = (view, schema) => Object.keys(view).reduce((acc, curr) => { 225 | const exists = ( 226 | (schema.properties && schema.properties[curr] !== undefined) 227 | || keyInXOf(curr, schema) 228 | ); 229 | if (exists) { 230 | acc[curr] = view[curr]; 231 | } 232 | return acc; 233 | }, {}); 234 | 235 | const generateHtmlPreview = (schema, view) => { 236 | schema = modSchemaForJSONEditor(schema); 237 | const htmlView = { 238 | schema_data: JSON.stringify(schema), 239 | default_view: JSON.stringify(filterExtraProperties(view, schema)) 240 | }; 241 | return Mustache.render(htmlStub.htmlData, htmlView); 242 | }; 243 | 244 | module.exports = { 245 | injectFormatsIntoSchema, 246 | addDepsToSchema, 247 | modSchemaForJSONEditor, 248 | filterExtraProperties, 249 | generateHtmlPreview 250 | }; 251 | -------------------------------------------------------------------------------- /docs/template_merging.md: -------------------------------------------------------------------------------- 1 | # Overlaid Definitions 2 | 3 | The way BIG-IP FAST generates parameter definitions can be surprising at times if that parameter shows up multiple times in the template text. 4 | 5 | When generating parameter definitions, BIG-IP FAST looks at the following locations in the following order, with later definitions overriding/modifying previous ones: 6 | 1. Embedded mustache tags in any merged templates. For example: {{var:f5:port}} 7 | 2. The definitions properties of any merged templates. Templates are merged by name using $ref inside a oneOf, anyOf, or allOf clause. 8 | 3. Embedded mustache tags in the primary template. 9 | 4. The definitions property in the primary template. 10 | 5. The parameters property in any merged templates. 11 | 6. The parameters property in the primary template. 12 | 13 | #### Notes: 14 | * If a duplicate Mustache tag exists in the template, then the last encountered tag is used for the definition. The order that Mustache tags are parsed in should not be assumed. 15 | * Properties within the definition (e.g., title, description, type, format, default, etc.) are merged together as they are found with newer data taking precedence over old data on key conflicts. 16 | * Values from the parameters property of YAML templates will be used in place of the default from the parameter definition but will not actually update the definition itself. 17 | 18 | 19 | # JSON Schema Basic Types 20 | 21 | ## Definitions 22 | Users can control the JSON Schema that FAST generates for parameters by providing parameter `definitions.` 23 | These definitions are added to the top-level definitions property of a template file. 24 | 25 | In the following example, we have a Template with a definition for ip addresses, named ip_addrs.yaml: 26 | ```yaml 27 | definitions: 28 | ip_addrs: 29 | type: array 30 | items: 31 | type: string, 32 | format: ipv4 33 | ``` 34 | 35 | And we can add that to the top-level of another template with this Template: 36 | ```yaml 37 | allOf: 38 | - $ref: "ip_addrs.yaml#" 39 | definitions: 40 | ports: 41 | type: array 42 | items: 43 | type: integer 44 | template: 45 | Services: 46 | {{#ip_addrs}} 47 | {{ . }}{{#ports}}:{{ . }}{{/ports}} 48 | {{/ip_addrs}} 49 | ``` 50 | 51 | Parameters: 52 | ```yaml 53 | ip_addrs: 54 | - 10.0.0.1 55 | - 10.0.0.2 56 | ports: 57 | - 80 58 | - 443 59 | ``` 60 | 61 | Output: 62 | ``` 63 | Services: 64 | 10.0.0.1:80 65 | 10.0.0.1:443 66 | 10.0.0.2:80 67 | 10.0.0.2:443 68 | ``` 69 | 70 | > **See Also:** [JSON Editor: $ref and definitions](https://github.com/json-editor/json-editor#ref-and-definitions) for additional code examples. 71 | 72 | **Array:** Arrays are used for ordered elements. 73 | In JSON, each element in an array may be of a different type. 74 | Elements of the array may be ordered or unordered based on the API being templated. 75 | This section covers typical JSON schema definitions for common patterns. 76 | 77 | For example, ip_addrs is defined with a type: array having items defined with type: string and format: ipv4 (more on formats later). 78 | 79 | ```yaml 80 | definitions: 81 | ip_addrs: 82 | type: array 83 | items: 84 | type: string, 85 | format: ipv4 86 | ``` 87 | 88 | **Numeric Types:** JSON has two numeric types; integer and number. 89 | An integer is used for integral (whole) numbers, while a number is any numerical value including integers and floating-point (decimal) numbers. 90 | 91 | **Ranges:** Combining minimum and maximum keywords for ranges or exclusiveMinimum and exclusiveMaximum for expressing exclusive ranges. 92 | The example below defines the range of port numbers as type: integer. 93 | 94 | ```yaml 95 | type: integer 96 | minimum: 0 97 | maximum: 65535 98 | ``` 99 | 100 | Another example is combining minimum and exclusiveMaximum. 101 | When using a minimum range of 0, then 0 is valid. 102 | With an exclusiveMaximum of 65535, 65534 is valid while 65535 is not. 103 | 104 | ```yaml 105 | type: number 106 | minimum: 0 107 | exclusiveMaximum: 65535 108 | ``` 109 | 110 | **String:** The string type is used for strings of text and may contain Unicode characters. 111 | The length of a string may be constrained using minLength and maxLength which cannot be a negative number. 112 | 113 | ```yaml 114 | type: string 115 | minLength: 2 116 | maxLength: 5 117 | ``` 118 | 119 | Along with the string type, JSON has some built in formats, using the format keyword. 120 | This allows for basic validation and can be used for certain strings such as IPv4 and IPv6 addressing. 121 | 122 | Regular Expressions (regexes) are used to match and extract parts of a string by searching for one or more matches of a search pattern. 123 | This example matches numbers from 0 and 255. 124 | String zeroTo255 = "([01]?[0-9]{1,2}|2[0-4][0-9]|25[0-5])" 125 | 126 | The string consists of three groups separated with a pipe. 127 | 1. [01]?[0-9]{1,2} - Matches any number between 0 and 199. [01]?: 0 or 1 may appear at most once at front of the number. [0-9]{1,2}: digits 0 to 9 may appear exactly once or twice on the 2nd or 3rd position in the number. 128 | 2. 2[0-4][0-9] - Matches numbers between 200 and 249, where the first digit is always 2, the second is between 0 and 4, and the third digit is any between 0 and 9, 129 | 3. 25[0-5]: (the 3rd group) matches numbers between 250 and 255, where 25 is always at front and the third digit is between 0 and 5. 130 | 131 | > **See Also:** JSON schema [Built-in Formats](https://json-schema.org/understanding-json-schema/reference/string.html?highlight=maxlength#built-in-formats) and [Regular Expressions](https://json-schema.org/understanding-json-schema/reference/string.html#id6) for more information. 132 | 133 | **Boolean:** The boolean type { type: boolean } matches two values; true or false and must be used in all lower case characters. 134 | 135 | 136 | # Combining Schema 137 | JSON uses the keywords allOf, anyOf and oneOf for combining schema together. 138 | BIG-IP FAST also uses they keywords of oneOf/allOf/anyOf for template merging, however this section is focused on JSON schema. 139 | 140 | **anyOf:** One or more of the contained schema is validated against the instance value. 141 | It is less restrictive than allOf as more than one of the same type may be specified. 142 | 143 | ```javascript 144 | { 145 | "anyOf": [ 146 | { "type": "string" }, 147 | { "type": "number" } 148 | ] 149 | } 150 | ``` 151 | 152 | **oneOf:** Validates against exactly one subschema even though multiple instances listed. 153 | For example, if multipleOf is set to 5 and 3, validation will pass on 10 and 9, but will fail on 2 as neither 5 nor 3 are multiples of 2. 154 | It will also fail on 15 as it is a multipleOf both 5 and 3 not oneOf. 155 | 156 | ```javascript 157 | { 158 | "oneOf": [ 159 | { "type": "number", "multipleOf": 5 }, 160 | { "type": "number", "multipleOf": 3 } 161 | ] 162 | } 163 | ``` 164 | 165 | **allOf:** All of the contained schemas must validate against the instance value. 166 | 167 | ```javascript 168 | { 169 | "allOf": [ 170 | { "type": "string" }, 171 | { "maxLength": 5 } 172 | ] 173 | } 174 | ``` 175 | 176 | > **Note:** When using allOf, be cautious of specifying multiple types such as `{ type: string }` and `{ type: number }` as a type cannot be a string and a number at the same time. 177 | 178 | When authoring templates using yaml, allOf takes on a special meaning by referencing another template in the set, known as Template Merging. 179 | * allOf will merge the schema of the merge template with external template(s) just as JSON schema will when generating schema for the merged templates 180 | * When a merge template is rendered, the JSON output of the templates will be merged together 181 | * Merge can be used to add additional configuration to a template 182 | 183 | ```yaml 184 | parameters: 185 | ... 186 | definitions: 187 | ... 188 | template: | 189 | ... 190 | allOf: 191 | - $ref: "tcp.yaml#" 192 | ``` 193 | 194 | > **See Also:** For detailed information, additional code examples and references, visit [Understanding JSON Schema](https://json-schema.org/understanding-json-schema/index.html) 195 | 196 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # v0.26.0 2 | ## Fixed 3 | * Vulnerabilities patched, but committed a partial of jsonplus-path package to vendor ourselves. This prevens FAST rpm loading failures on BIG-IP when node can't find the only patched version of it in npm: 10.3.0 4 | 5 | * # v0.25.0 6 | ## Changed 7 | * Update dependencies 8 | 9 | ## Added 10 | * Add AuditProcessor 11 | 12 | # v0.24.0 13 | ## Changed 14 | * template: provide more useful error message on duplicate keys during template rendering 15 | 16 | # v0.23.0 17 | ## Fixed 18 | * cli: Improve JSON output for errors on validateTemplateSet and validate 19 | * cli: Fix JSON output for validateTemplateSet, packageTemplateSet, and htmlpreview 20 | 21 | ## Changed 22 | * template: Include Mustache errors in getValidationErrors() 23 | * template: Make validation errors from failed pattern matches shorter (move expected pattern to "details") 24 | * template: Make validation errors from failed enum matches shorter (move allowed values to "details") 25 | 26 | # v0.22.1 27 | ## Fixed 28 | * template: Fix "paramters" typo in validateParameters() error 29 | 30 | # v0.22.0 31 | ## Added 32 | * cli: Add --json-output flag to change all output to JSON 33 | 34 | ## Changed 35 | * template: Change the Error message from validateParameters() to be simpler 36 | * template: Move validation errors and parameters from the validateParameters() Error message string to validationErrors and parameters properties on the Error object 37 | * template: Show all validation errors when calling validateParameters() 38 | * template: Parse the Ajv validation errors from validateParameters() and create easier to read/understand error messages 39 | 40 | # v0.21.0 41 | ## Added 42 | * template: Allow customizing input transform behavior via fast.transformStrategies 43 | 44 | ## Fixed 45 | * Fix undefined fast.postProcessStrategies 46 | * template: Fix using an object parameter as input to a section 47 | 48 | ## Changed 49 | * template: JsonTransformStrategy is now only used for 'application/json' contentType 50 | 51 | # v0.20.2 52 | ## Fixed 53 | * Add CompositeTemplateProvider to index 54 | 55 | # v0.20.1 56 | ## Changed 57 | * Locked json-schema-ref-parser dependency to 9.0.9 (9.1.x is breaking template loading) 58 | 59 | # v0.20.0 60 | ## Added 61 | * Add a CompositeTemplateProvider to aggregate results from multiple template providers 62 | 63 | ## Changed 64 | * Update dependencies 65 | 66 | # v0.19.1 67 | ## Changed 68 | * Update dependencies 69 | 70 | # v0.19.0 71 | ## Added 72 | * template: Add dataFile parameter property for including arbitrary text from files 73 | 74 | ## Fixed 75 | * Fix loading sub-templates with GitHubTemplateProvider 76 | 77 | # v0.18.0 78 | ## Added 79 | * Add a GitHubSchemaProvider and GitHubTemplateProvider 80 | 81 | ## Changed 82 | * Updated dependencies 83 | * Stop pulling in pkg as a dev dependency 84 | * Expose BaseTemplateProvider class 85 | 86 | # v0.17.0 87 | ## Fixed 88 | * guiUtils: Prefer defaults from top-level templates when merging allOf templates 89 | * template: Fix duplicate items in required property when merging sections (issue #23) 90 | 91 | # v0.16.0 92 | ## Fixed 93 | * schema_provider: Fix loading schema files with a '.' in the filename 94 | * template: Fix parameters from Mustache sections getting listed as required even if they have a default value 95 | * guiUtils: Fix merging nested mixins 96 | 97 | # v0.15.0 98 | ## Changed 99 | * template: Merge duplicate section definitions instead of overwriting 100 | 101 | # v0.14.0 102 | ## Fixed 103 | * template: Fix merging array items definitions with custom types 104 | * template: Fix over-aggressive cleaning of definitions referenced in "items" keyword 105 | * template: Fix losing definitions from merged in templates 106 | * template: Fix missing description when merging templates 107 | 108 | ## Changed 109 | * ResourceCache: Improve cache utilization for concurrent requests 110 | * template: Do not mark properties with defaults as required 111 | * template: Do not automatically supply default values for primitive types 112 | 113 | # v0.13.0 114 | ## Added 115 | * TemplateProvider: Return template description and title with getSetData() 116 | 117 | # v0.12.0 118 | ## Added 119 | * template: Allow using a TemplateProvider to resolve external JSON references 120 | 121 | ## Fixed 122 | * TemplateProvider: Fix template sets with matching prefixes from getting listed together 123 | 124 | ## Changed 125 | * Update js-yaml dependency to 4.x 126 | * Switch from archiver to adm-zip to reduce transitive dependencies 127 | * Remove uuid dependency 128 | * Remove json-schema-merge-allof dependency 129 | 130 | # v0.11.0 131 | ## Added 132 | * template: Allow overriding automatic dependencies with definitions 133 | 134 | ## Fixed 135 | * guiUtils: Fix merging dependencies when collapsing allOf items 136 | * template: Fix merging dependencies when using partials 137 | 138 | ## Changed 139 | * Updated dependencies 140 | 141 | # v0.10.0 142 | ## Added 143 | 144 | ## Fixed 145 | * template: Fix duplicate allOf property 146 | * template: Fix gathering tokens for mathExpressions on merged templates 147 | 148 | ## Changed 149 | * template: Skip creating unused parameter validators on merged-in templates 150 | * guiUtils: Remove hidden mathExpression parameters from the GUI schema 151 | * htmlpreview: Pull JSON Editor from a CDN 152 | * cli: Display errors for each template when using validateTemplateSet 153 | 154 | # v0.9.0 155 | ## Added 156 | * template: Add better support for JSON Editor "info" format 157 | * template_provider: Add FsSingleTemplateProvider convenience class to load a single template set 158 | * template: Add support for YAML contentType (text/x-yaml, application/x-yaml, and application/yaml are all accepted) 159 | * template: Add support for calculating parameter values from arithmetic expressions 160 | 161 | ## Fixed 162 | * guiUtils: Fix "No resolver found for key propertyOrder" error when collapsing multiple allOf items 163 | * guiUtils: Fix "No resolver found for key invertDependency" when collapsing allOf items 164 | * template: Fix for duplicate items in dependencies 165 | * template: Fix running JSON and YAML post-process strategies on empty strings 166 | 167 | ## Changed 168 | * Switch from internal httpUtils library to axios (httpUtils has also been removed) 169 | * template: Prefer defaults from the current template over merged in templates 170 | * template: Allow definitions to override values in merged templates even if the parameters are not present in the template text 171 | * template: Significantly reduce the size of the Template object 172 | * template: Remove typeDefinitions from the public API 173 | * template: Prune unused definitions (Template.definitions no longer contains the original definitions from the template file) 174 | 175 | # v0.8.0 176 | ## Added 177 | * template: Support extended user types (e.g., "var:lib:type") for sections and partials 178 | * template: Add post-processing strategies and add one for 'application/json' to cleanup dangling commas 179 | * cli: Add guiSchema sub command that runs the parameters schema through guiUtils.modSchemaForJSONEditor() before displaying it 180 | 181 | ## Fixed 182 | * template: Fix using full Mustache variable names (e.g., "var:lib:type") for dependencies and requires 183 | * template: Fix sections with a dot item overriding user definitions 184 | * template: Add missing doc strings for HTTP fetching and forwarding functions 185 | * template: Fix missing defaults from merged templates 186 | * guiUtils: Additional fixes for allOf schema in modSchemaForJSONEditor() 187 | * guiUtils: Do not error if a dependency is missing from the properties 188 | 189 | ## Changed 190 | * cli: Run fetchHttp() as part of render command 191 | * guiUtils: modSchemaForJSONEditor() no longer modifies in place 192 | 193 | # v0.7.0 194 | ## Added 195 | * Add jsdoc-style docs to classes mentioned in the README 196 | * Add option to get variable values from HTTP requests 197 | * Add Template.forwardHttp() to forward a rendered template result to an HTTP server 198 | 199 | ## Fixed 200 | * Improve guiUtils.filterExtraProperties() when using template merging 201 | * guiUtils: Improve form render order when using allOf 202 | 203 | ## Changed 204 | * guiUtils: Use JSON Editor 'select' format for arrays of unique enum items 205 | * guiUtils: Flatten allOf schema in modSchemaForJSONEditor 206 | * template: Return an empty array instead of undefined when transforming an undefined array 207 | 208 | # v0.6.0 209 | ## Added 210 | * Expose Template mergeStrategies in index.js 211 | * Cache GET requests to AS3 declare endpoint 212 | * Add "responses" information from AS3 tasks to FAST tasks 213 | * Add operation information (e.g., update vs delete) to FAST tasks 214 | * Merge definitions and default parameters from base templates 215 | * Save additional, top-level properties found on YAML templates 216 | 217 | ## Fixed 218 | * Missing type schema when merging templates 219 | 220 | ## Changed 221 | * Move empty-string checks out of template merge strategies 222 | * Remove AS3Driver 223 | 224 | # v0.5.1 225 | ## Fixed 226 | * Bad reference to atg-storage 227 | 228 | # v0.5 229 | ## Added 230 | * CLI: Support YAML for parameter files 231 | * AS3 driver: Add deleteApplications() function 232 | * Support combining templates via oneOf/allOf/anyOf 233 | * Support $ref in template definitions (http $refs are not supported) 234 | 235 | ## Fixed 236 | 237 | ## Changed 238 | * Report a better error message when Ajv fails to compile a schema 239 | * Improve error reporting in the CLI 240 | 241 | # v0.4 242 | Initial, independent release (previously part of [f5-appsvcs-templates](https://github.com/F5networks/f5-appsvcs-templates)) 243 | -------------------------------------------------------------------------------- /test/template_provider.js: -------------------------------------------------------------------------------- 1 | /* Copyright 2021 F5 Networks, Inc. 2 | * 3 | * Licensed under the Apache License, Version 2.0 (the "License"); 4 | * you may not use this file except in compliance with the License. 5 | * You may obtain a copy of the License at 6 | * 7 | * http://www.apache.org/licenses/LICENSE-2.0 8 | * 9 | * Unless required by applicable law or agreed to in writing, software 10 | * distributed under the License is distributed on an "AS IS" BASIS, 11 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | * See the License for the specific language governing permissions and 13 | * limitations under the License. 14 | */ 15 | 16 | /* eslint-disable prefer-arrow-callback */ 17 | /* eslint-disable func-names */ 18 | /* eslint-disable no-console */ 19 | 20 | 'use strict'; 21 | 22 | const nock = require('nock'); 23 | const chai = require('chai'); 24 | const chaiAsPromised = require('chai-as-promised'); 25 | 26 | chai.use(chaiAsPromised); 27 | const assert = chai.assert; 28 | 29 | const StorageMemory = require('@f5devcentral/atg-storage').StorageMemory; 30 | const { 31 | FsTemplateProvider, 32 | FsSingleTemplateProvider, 33 | DataStoreTemplateProvider, 34 | CompositeTemplateProvider 35 | } = require('../lib/template_provider'); 36 | 37 | const { GitHubTemplateProvider } = require('../lib/github_provider'); 38 | const { nockGitHubAPI } = require('./githubMock'); 39 | 40 | const templatesPath = './test/templatesets'; 41 | 42 | function runSharedTests(createProvider) { 43 | it('construct', function () { 44 | const provider = createProvider(); 45 | assert.ok(provider); 46 | }); 47 | it('load_list', function () { 48 | const provider = createProvider(); 49 | return provider.list() 50 | .then((tmplList) => { 51 | assert.deepStrictEqual(tmplList.sort(), [ 52 | 'test/base', 53 | 'test/combine', 54 | 'test/complex', 55 | 'test/extended', 56 | 'test/simple', 57 | 'test/simple_udp' 58 | ]); 59 | }); 60 | }); 61 | it('load_list_filter', function () { 62 | const provider = createProvider(['foo']); 63 | return provider.list() 64 | .then((templates) => { 65 | assert.ok(templates); 66 | assert.strictEqual(templates.length, 0); 67 | }); 68 | }); 69 | it('list_sets', function () { 70 | const provider = createProvider(); 71 | return assert.becomes(provider.listSets(), ['test']); 72 | }); 73 | it('load_single_complex', function () { 74 | const provider = createProvider(); 75 | return provider.fetch('test/complex') 76 | .then((tmpl) => { 77 | assert.ok(tmpl); 78 | const schema = tmpl.getParametersSchema(); 79 | console.log(JSON.stringify(schema, null, 2)); 80 | assert.strictEqual(schema.title, 'chat window'); 81 | assert.strictEqual(schema.description, ''); 82 | assert.strictEqual(tmpl.target, 'as3'); 83 | assert.ok(tmpl._partials.chatlog); 84 | assert.strictEqual(schema.properties.fromFile.default, 'Lorem ipsum\n'); 85 | }); 86 | }); 87 | it('load_single_with_schema', function () { 88 | const provider = createProvider(); 89 | return provider.fetch('test/simple') 90 | .then((tmpl) => { 91 | assert.ok(tmpl); 92 | console.log(JSON.stringify(tmpl, null, 2)); 93 | assert.strictEqual(tmpl.title, 'Simple YAML file'); 94 | assert.strictEqual(tmpl.target, 'as3'); 95 | }); 96 | }); 97 | it('load_sub_template', function () { 98 | const provider = createProvider(); 99 | return provider.fetch('test/extended') 100 | .then((tmpl) => { 101 | assert.ok(tmpl); 102 | console.log(JSON.stringify(tmpl, null, 2)); 103 | assert.strictEqual(tmpl.title, 'Main template'); 104 | assert.strictEqual(tmpl._allOf[0].title, 'Base Template'); 105 | }); 106 | }); 107 | it('load_single_bad', function () { 108 | const provider = createProvider(); 109 | return assert.isRejected(provider.fetch('does_not_exist')); 110 | }); 111 | it('load_multiple', function () { 112 | const provider = createProvider(); 113 | return assert.isFulfilled(provider.fetch('test/simple')) 114 | .then(() => assert.isFulfilled(provider.fetch('test/complex'))) 115 | .then(() => assert.isFulfilled(provider.fetch('test/simple'))); 116 | }); 117 | it('get_schemas', function () { 118 | const provider = createProvider(); 119 | return provider.getSchemas() 120 | .then((schemas) => { 121 | const schemaNames = Object.keys(schemas); 122 | console.log(JSON.stringify(schemas, null, 2)); 123 | assert(schemaNames.includes('test/types'), 'expected test/types to be in the schema list'); 124 | }); 125 | }); 126 | it('list_tmpl_sources', function () { 127 | const provider = createProvider(); 128 | return assert.becomes(provider.getNumTemplateSourceTypes('test'), { 129 | MST: 1, 130 | YAML: 5 131 | }) 132 | .then(() => assert.becomes(provider.getNumTemplateSourceTypes(), { 133 | MST: 1, 134 | YAML: 5 135 | })); 136 | }); 137 | it('num_schemas', function () { 138 | const provider = createProvider(); 139 | return assert.becomes(provider.getNumSchema('test'), 1) 140 | .then(() => assert.becomes(provider.getNumSchema(), 1)); 141 | }); 142 | it('fetch_set', function () { 143 | const provider = createProvider(); 144 | return provider.fetchSet('test') 145 | .then((templates) => { 146 | console.log(JSON.stringify(templates, null, 2)); 147 | assert.ok(templates['test/simple']); 148 | assert.ok(templates['test/complex']); 149 | }); 150 | }); 151 | it('get_set_data', function () { 152 | const provider = createProvider(); 153 | return provider.getSetData('test') 154 | .then((setData) => { 155 | console.log(JSON.stringify(setData, null, 2)); 156 | assert.ok(setData); 157 | 158 | assert.strictEqual(setData.name, 'test'); 159 | assert.strictEqual(setData.supported, false); 160 | 161 | const tmplNames = setData.templates.map(x => x.name).sort(); 162 | assert.deepStrictEqual(tmplNames, [ 163 | 'test/base', 164 | 'test/combine', 165 | 'test/complex', 166 | 'test/extended', 167 | 'test/simple', 168 | 'test/simple_udp' 169 | ]); 170 | const tmplDesc = setData.templates.map(x => x.description).sort(); 171 | assert.deepStrictEqual(tmplDesc, [ 172 | '', 173 | '', 174 | '', 175 | 'A simple template to test we can handle the .yaml file extension', 176 | 'An example of how to combine templates', 177 | 'Simple UDP load balancer using the same port on client and server side.\nUses AS3 template: udp.' 178 | ]); 179 | const schemaNames = setData.schemas.map(x => x.name).sort(); 180 | assert.deepStrictEqual(schemaNames, [ 181 | 'test/types' 182 | ]); 183 | }); 184 | }); 185 | } 186 | 187 | describe('template provider tests', function () { 188 | describe('FsTemplateProvider', function () { 189 | runSharedTests( 190 | filtered => new FsTemplateProvider(templatesPath, filtered) 191 | ); 192 | it('load_single_mst', function () { 193 | const provider = new FsTemplateProvider(templatesPath); 194 | return provider.fetch('test/simple_udp') 195 | .then((tmpl) => { 196 | assert.ok(tmpl); 197 | }); 198 | }); 199 | it('load_single_yml', function () { 200 | const provider = new FsTemplateProvider(templatesPath); 201 | return provider.fetch('test/complex') 202 | .then((tmpl) => { 203 | assert.ok(tmpl); 204 | }); 205 | }); 206 | it('bad_tmpl_path', function () { 207 | const provider = new FsTemplateProvider('bad/path'); 208 | return Promise.all([ 209 | assert.isRejected(provider.list()), 210 | assert.isRejected(provider.fetch('simple_udp')) 211 | ]); 212 | }); 213 | it('remove_tmpl_set', function () { 214 | const provider = new FsTemplateProvider(templatesPath); 215 | return assert.isRejected(provider.removeSet('example'), /not implemented/); 216 | }); 217 | }); 218 | describe('FsSingleTemplateProvider', function () { 219 | it('load_single_mst', function () { 220 | const provider = new FsSingleTemplateProvider(`${templatesPath}/test`); 221 | return provider.fetch('test/simple_udp') 222 | .then((tmpl) => { 223 | assert.ok(tmpl); 224 | }); 225 | }); 226 | }); 227 | describe('DataStoreTemplateProvider', function () { 228 | const testStorage = new StorageMemory(); 229 | before(function () { 230 | testStorage.data = {}; 231 | return DataStoreTemplateProvider.fromFs(testStorage, templatesPath); 232 | }); 233 | const createProvider = filtered => new DataStoreTemplateProvider(testStorage, filtered); 234 | 235 | runSharedTests(createProvider); 236 | 237 | it('load_single_bad_tmpl_path', function () { 238 | const provider = createProvider(); 239 | return assert.isRejected(provider.fetch('test/badpath')); 240 | }); 241 | it('remove_tmpl_set', function () { 242 | const provider = createProvider(); 243 | return assert.isFulfilled(provider.removeSet('test')) 244 | .then(() => assert.becomes(provider.listSets(), [])); 245 | }); 246 | it('remove_tmpl_set_missing', function () { 247 | const provider = createProvider(); 248 | return assert.isRejected(provider.removeSet('does_not_exist'), /failed to find template set/); 249 | }); 250 | }); 251 | describe('GitHubTemplateProvider', function () { 252 | const repo = 'f5-test/f5-fast-test-templatesets'; 253 | before(() => nockGitHubAPI(repo, './test/templatesets')); 254 | after(() => nock.cleanAll()); 255 | 256 | runSharedTests( 257 | filtered => new GitHubTemplateProvider( 258 | repo, 259 | { 260 | filteredSets: filtered, 261 | apiToken: 'secret' 262 | } 263 | ) 264 | ); 265 | }); 266 | describe('CompositeTemplateProvider', function () { 267 | const testStorage = new StorageMemory(); 268 | before(function () { 269 | testStorage.data = {}; 270 | return DataStoreTemplateProvider.fromFs(testStorage, templatesPath); 271 | }); 272 | 273 | runSharedTests( 274 | filtered => new CompositeTemplateProvider([ 275 | new FsTemplateProvider(templatesPath, filtered), 276 | new DataStoreTemplateProvider(testStorage, filtered) 277 | ]) 278 | ); 279 | }); 280 | }); 281 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | 2 | Apache License 3 | Version 2.0, January 2004 4 | http://www.apache.org/licenses/ 5 | 6 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 7 | 8 | 1. Definitions. 9 | 10 | "License" shall mean the terms and conditions for use, reproduction, 11 | and distribution as defined by Sections 1 through 9 of this document. 12 | 13 | "Licensor" shall mean the copyright owner or entity authorized by 14 | the copyright owner that is granting the License. 15 | 16 | "Legal Entity" shall mean the union of the acting entity and all 17 | other entities that control, are controlled by, or are under common 18 | control with that entity. For the purposes of this definition, 19 | "control" means (i) the power, direct or indirect, to cause the 20 | direction or management of such entity, whether by contract or 21 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 22 | outstanding shares, or (iii) beneficial ownership of such entity. 23 | 24 | "You" (or "Your") shall mean an individual or Legal Entity 25 | exercising permissions granted by this License. 26 | 27 | "Source" form shall mean the preferred form for making modifications, 28 | including but not limited to software source code, documentation 29 | source, and configuration files. 30 | 31 | "Object" form shall mean any form resulting from mechanical 32 | transformation or translation of a Source form, including but 33 | not limited to compiled object code, generated documentation, 34 | and conversions to other media types. 35 | 36 | "Work" shall mean the work of authorship, whether in Source or 37 | Object form, made available under the License, as indicated by a 38 | copyright notice that is included in or attached to the work 39 | (an example is provided in the Appendix below). 40 | 41 | "Derivative Works" shall mean any work, whether in Source or Object 42 | form, that is based on (or derived from) the Work and for which the 43 | editorial revisions, annotations, elaborations, or other modifications 44 | represent, as a whole, an original work of authorship. For the purposes 45 | of this License, Derivative Works shall not include works that remain 46 | separable from, or merely link (or bind by name) to the interfaces of, 47 | the Work and Derivative Works thereof. 48 | 49 | "Contribution" shall mean any work of authorship, including 50 | the original version of the Work and any modifications or additions 51 | to that Work or Derivative Works thereof, that is intentionally 52 | submitted to Licensor for inclusion in the Work by the copyright owner 53 | or by an individual or Legal Entity authorized to submit on behalf of 54 | the copyright owner. For the purposes of this definition, "submitted" 55 | means any form of electronic, verbal, or written communication sent 56 | to the Licensor or its representatives, including but not limited to 57 | communication on electronic mailing lists, source code control systems, 58 | and issue tracking systems that are managed by, or on behalf of, the 59 | Licensor for the purpose of discussing and improving the Work, but 60 | excluding communication that is conspicuously marked or otherwise 61 | designated in writing by the copyright owner as "Not a Contribution." 62 | 63 | "Contributor" shall mean Licensor and any individual or Legal Entity 64 | on behalf of whom a Contribution has been received by Licensor and 65 | subsequently incorporated within the Work. 66 | 67 | 2. Grant of Copyright License. Subject to the terms and conditions of 68 | this License, each Contributor hereby grants to You a perpetual, 69 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 70 | copyright license to reproduce, prepare Derivative Works of, 71 | publicly display, publicly perform, sublicense, and distribute the 72 | Work and such Derivative Works in Source or Object form. 73 | 74 | 3. Grant of Patent License. Subject to the terms and conditions of 75 | this License, each Contributor hereby grants to You a perpetual, 76 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 77 | (except as stated in this section) patent license to make, have made, 78 | use, offer to sell, sell, import, and otherwise transfer the Work, 79 | where such license applies only to those patent claims licensable 80 | by such Contributor that are necessarily infringed by their 81 | Contribution(s) alone or by combination of their Contribution(s) 82 | with the Work to which such Contribution(s) was submitted. If You 83 | institute patent litigation against any entity (including a 84 | cross-claim or counterclaim in a lawsuit) alleging that the Work 85 | or a Contribution incorporated within the Work constitutes direct 86 | or contributory patent infringement, then any patent licenses 87 | granted to You under this License for that Work shall terminate 88 | as of the date such litigation is filed. 89 | 90 | 4. Redistribution. You may reproduce and distribute copies of the 91 | Work or Derivative Works thereof in any medium, with or without 92 | modifications, and in Source or Object form, provided that You 93 | meet the following conditions: 94 | 95 | (a) You must give any other recipients of the Work or 96 | Derivative Works a copy of this License; and 97 | 98 | (b) You must cause any modified files to carry prominent notices 99 | stating that You changed the files; and 100 | 101 | (c) You must retain, in the Source form of any Derivative Works 102 | that You distribute, all copyright, patent, trademark, and 103 | attribution notices from the Source form of the Work, 104 | excluding those notices that do not pertain to any part of 105 | the Derivative Works; and 106 | 107 | (d) If the Work includes a "NOTICE" text file as part of its 108 | distribution, then any Derivative Works that You distribute must 109 | include a readable copy of the attribution notices contained 110 | within such NOTICE file, excluding those notices that do not 111 | pertain to any part of the Derivative Works, in at least one 112 | of the following places: within a NOTICE text file distributed 113 | as part of the Derivative Works; within the Source form or 114 | documentation, if provided along with the Derivative Works; or, 115 | within a display generated by the Derivative Works, if and 116 | wherever such third-party notices normally appear. The contents 117 | of the NOTICE file are for informational purposes only and 118 | do not modify the License. You may add Your own attribution 119 | notices within Derivative Works that You distribute, alongside 120 | or as an addendum to the NOTICE text from the Work, provided 121 | that such additional attribution notices cannot be construed 122 | as modifying the License. 123 | 124 | You may add Your own copyright statement to Your modifications and 125 | may provide additional or different license terms and conditions 126 | for use, reproduction, or distribution of Your modifications, or 127 | for any such Derivative Works as a whole, provided Your use, 128 | reproduction, and distribution of the Work otherwise complies with 129 | the conditions stated in this License. 130 | 131 | 5. Submission of Contributions. Unless You explicitly state otherwise, 132 | any Contribution intentionally submitted for inclusion in the Work 133 | by You to the Licensor shall be under the terms and conditions of 134 | this License, without any additional terms or conditions. 135 | Notwithstanding the above, nothing herein shall supersede or modify 136 | the terms of any separate license agreement you may have executed 137 | with Licensor regarding such Contributions. 138 | 139 | 6. Trademarks. This License does not grant permission to use the trade 140 | names, trademarks, service marks, or product names of the Licensor, 141 | except as required for reasonable and customary use in describing the 142 | origin of the Work and reproducing the content of the NOTICE file. 143 | 144 | 7. Disclaimer of Warranty. Unless required by applicable law or 145 | agreed to in writing, Licensor provides the Work (and each 146 | Contributor provides its Contributions) on an "AS IS" BASIS, 147 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 148 | implied, including, without limitation, any warranties or conditions 149 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 150 | PARTICULAR PURPOSE. You are solely responsible for determining the 151 | appropriateness of using or redistributing the Work and assume any 152 | risks associated with Your exercise of permissions under this License. 153 | 154 | 8. Limitation of Liability. In no event and under no legal theory, 155 | whether in tort (including negligence), contract, or otherwise, 156 | unless required by applicable law (such as deliberate and grossly 157 | negligent acts) or agreed to in writing, shall any Contributor be 158 | liable to You for damages, including any direct, indirect, special, 159 | incidental, or consequential damages of any character arising as a 160 | result of this License or out of the use or inability to use the 161 | Work (including but not limited to damages for loss of goodwill, 162 | work stoppage, computer failure or malfunction, or any and all 163 | other commercial damages or losses), even if such Contributor 164 | has been advised of the possibility of such damages. 165 | 166 | 9. Accepting Warranty or Additional Liability. While redistributing 167 | the Work or Derivative Works thereof, You may choose to offer, 168 | and charge a fee for, acceptance of support, warranty, indemnity, 169 | or other liability obligations and/or rights consistent with this 170 | License. However, in accepting such obligations, You may act only 171 | on Your own behalf and on Your sole responsibility, not on behalf 172 | of any other Contributor, and only if You agree to indemnify, 173 | defend, and hold each Contributor harmless for any liability 174 | incurred by, or claims asserted against, such Contributor by reason 175 | of your accepting any such warranty or additional liability. 176 | 177 | END OF TERMS AND CONDITIONS 178 | 179 | APPENDIX: How to apply the Apache License to your work. 180 | 181 | To apply the Apache License to your work, attach the following 182 | boilerplate notice, with the fields enclosed by brackets "[]" 183 | replaced with your own identifying information. (Don't include 184 | the brackets!) The text should be enclosed in the appropriate 185 | comment syntax for the file format. We also recommend that a 186 | file or class name and description of purpose be included on the 187 | same "printed page" as the copyright notice for easier 188 | identification within third-party archives. 189 | 190 | Copyright [yyyy] [name of copyright owner] 191 | 192 | Licensed under the Apache License, Version 2.0 (the "License"); 193 | you may not use this file except in compliance with the License. 194 | You may obtain a copy of the License at 195 | 196 | http://www.apache.org/licenses/LICENSE-2.0 197 | 198 | Unless required by applicable law or agreed to in writing, software 199 | distributed under the License is distributed on an "AS IS" BASIS, 200 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 201 | See the License for the specific language governing permissions and 202 | limitations under the License. 203 | -------------------------------------------------------------------------------- /test/gui_utils.js: -------------------------------------------------------------------------------- 1 | /* Copyright 2021 F5 Networks, Inc. 2 | * 3 | * Licensed under the Apache License, Version 2.0 (the "License"); 4 | * you may not use this file except in compliance with the License. 5 | * You may obtain a copy of the License at 6 | * 7 | * http://www.apache.org/licenses/LICENSE-2.0 8 | * 9 | * Unless required by applicable law or agreed to in writing, software 10 | * distributed under the License is distributed on an "AS IS" BASIS, 11 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | * See the License for the specific language governing permissions and 13 | * limitations under the License. 14 | */ 15 | 16 | /* eslint-disable prefer-arrow-callback */ 17 | /* eslint-disable func-names */ 18 | /* eslint-disable no-console */ 19 | 20 | 'use strict'; 21 | 22 | const assert = require('assert'); 23 | 24 | const guiUtils = require('../lib/gui_utils'); 25 | 26 | describe('GUI utils test', function () { 27 | it('add_title', function () { 28 | const schema = guiUtils.modSchemaForJSONEditor({}); 29 | assert.strictEqual(schema.title, 'Template'); 30 | }); 31 | it('inject_formats', function () { 32 | let schema = { 33 | properties: { 34 | bool: { type: 'boolean' }, 35 | table: { type: 'array' }, 36 | str: { type: 'string' }, 37 | longstr: { type: 'string', format: 'text' }, 38 | multiselect: { 39 | type: 'array', 40 | uniqueItems: true, 41 | items: { 42 | type: 'string', 43 | enum: ['val1', 'val2'] 44 | } 45 | } 46 | } 47 | }; 48 | schema = guiUtils.modSchemaForJSONEditor(schema); 49 | assert.strictEqual(schema.properties.bool.format, 'checkbox'); 50 | assert.strictEqual(schema.properties.table.format, 'table'); 51 | assert.strictEqual(schema.properties.str.format, undefined); 52 | assert.strictEqual(schema.properties.longstr.format, 'textarea'); 53 | assert.strictEqual(schema.properties.multiselect.format, 'select'); 54 | }); 55 | it('add_deps', function () { 56 | let schema = { 57 | properties: { 58 | useFoo: { type: 'boolean' }, 59 | existingFoo: { type: 'boolean' }, 60 | foo: { type: 'string', invertDependency: ['existingFoo'] }, 61 | skipBar: { type: 'boolean' }, 62 | bar: { type: 'string', invertDependency: ['skipBar'] } 63 | }, 64 | dependencies: { 65 | foo: ['existingFoo', 'useFoo'], 66 | bar: ['skipBar'], 67 | existingFoo: ['useFoo'] 68 | } 69 | }; 70 | schema = guiUtils.modSchemaForJSONEditor(schema); 71 | console.log(JSON.stringify(schema, null, 2)); 72 | assert.deepStrictEqual(schema.properties.foo.options.dependencies, { useFoo: true, existingFoo: false }); 73 | assert.deepStrictEqual(schema.properties.bar.options.dependencies, { skipBar: false }); 74 | }); 75 | it('all_of_fixes', function () { 76 | let schema = { 77 | title: 'top level', 78 | properties: { 79 | showFirst: { type: 'string' }, 80 | foo: { type: 'string' } 81 | }, 82 | allOf: [ 83 | { 84 | title: 'sub 1', 85 | properties: { 86 | baz: { type: 'integer' } 87 | } 88 | }, 89 | { 90 | title: 'sub 2', 91 | properties: { 92 | baz: { type: 'integer' } 93 | } 94 | } 95 | ] 96 | }; 97 | schema = guiUtils.modSchemaForJSONEditor(schema); 98 | console.log(JSON.stringify(schema, null, 2)); 99 | 100 | // Order fixes 101 | const expectedOrder = ['baz', 'showFirst', 'foo']; 102 | const actualOrder = Object.keys(schema.properties).sort((a, b) => ( 103 | schema.properties[a].propertyOrder - schema.properties[b].propertyOrder 104 | )); 105 | assert.deepStrictEqual(actualOrder, expectedOrder); 106 | 107 | // Flatten allOf 108 | assert.strictEqual(schema.allOf, undefined); 109 | 110 | // Preserve top-level title 111 | assert.strictEqual(schema.title, 'top level'); 112 | }); 113 | it('all_of_defaults', function () { 114 | let schema = { 115 | title: 'extended', 116 | properties: { 117 | port: { 118 | default: 45 119 | } 120 | }, 121 | allOf: [ 122 | { 123 | title: 'base', 124 | properties: { 125 | port: { 126 | type: 'integer', 127 | default: 443 128 | } 129 | } 130 | } 131 | ] 132 | }; 133 | schema = guiUtils.modSchemaForJSONEditor(schema); 134 | console.log(JSON.stringify(schema, null, 2)); 135 | 136 | const props = schema.properties; 137 | assert.strictEqual(props.port.default, 45); 138 | }); 139 | it('all_of_merge_dependencies', function () { 140 | let schema = { 141 | type: 'object', 142 | allOf: [ 143 | { 144 | type: 'object', 145 | properties: { 146 | section1: { 147 | type: 'boolean', 148 | default: false 149 | }, 150 | foo: { 151 | type: 'string', 152 | default: '' 153 | } 154 | }, 155 | required: [ 156 | 'section1' 157 | ], 158 | dependencies: { 159 | foo: [ 160 | 'section1' 161 | ] 162 | }, 163 | title: 'Section1' 164 | }, 165 | { 166 | type: 'object', 167 | properties: { 168 | section2: { 169 | type: 'boolean', 170 | default: false 171 | }, 172 | foo: { 173 | type: 'string', 174 | default: '' 175 | } 176 | }, 177 | required: [ 178 | 'section2' 179 | ], 180 | dependencies: { 181 | foo: [ 182 | 'section2' 183 | ] 184 | }, 185 | title: 'Section2' 186 | }, 187 | { 188 | type: 'object', 189 | properties: { 190 | section3: { 191 | type: 'boolean', 192 | default: false 193 | }, 194 | foo: { 195 | type: 'string', 196 | default: '', 197 | invertDependency: [ 198 | 'section3' 199 | ] 200 | } 201 | }, 202 | required: [ 203 | 'section3' 204 | ], 205 | dependencies: { 206 | foo: [ 207 | 'section3' 208 | ] 209 | }, 210 | title: 'Section3' 211 | } 212 | ] 213 | }; 214 | 215 | schema = guiUtils.modSchemaForJSONEditor(schema); 216 | console.log(JSON.stringify(schema, null, 2)); 217 | 218 | assert.deepStrictEqual(schema.dependencies.foo, ['section1', 'section2', 'section3']); 219 | assert.strictEqual(schema.properties.foo.options.dependencies.section3, false); 220 | }); 221 | it('merge_mixins', function () { 222 | let schema = { 223 | properties: { 224 | showFirst: { type: 'string' }, 225 | foo: { type: 'string' } 226 | }, 227 | anyOf: [ 228 | {}, 229 | { 230 | properties: { 231 | baz: { type: 'integer' } 232 | }, 233 | anyOf: [ 234 | {}, 235 | { 236 | properties: { 237 | nested: { type: 'integer' } 238 | } 239 | } 240 | ] 241 | } 242 | ] 243 | }; 244 | schema = guiUtils.modSchemaForJSONEditor(schema); 245 | console.log(JSON.stringify(schema, null, 2)); 246 | 247 | assert.ok(schema.properties.baz); 248 | assert.ok(schema.properties.nested); 249 | 250 | // Order fixes 251 | const expectedOrder = ['showFirst', 'foo', 'baz', 'nested']; 252 | const actualOrder = Object.keys(schema.properties).sort((a, b) => ( 253 | schema.properties[a].propertyOrder - schema.properties[b].propertyOrder 254 | )); 255 | assert.deepStrictEqual(actualOrder, expectedOrder); 256 | 257 | // Flatten anyOf 258 | assert.strictEqual(schema.anyOf, undefined); 259 | }); 260 | it('remove_math_expressions', function () { 261 | let schema = { 262 | properties: { 263 | remove: { 264 | type: 'string', 265 | format: 'hidden', 266 | mathExpression: '' 267 | }, 268 | keep: { 269 | type: 'string', 270 | format: 'text', 271 | mathExpression: '' 272 | }, 273 | keep2: { 274 | type: 'string', 275 | title: 'important stuff', 276 | mathExpression: '' 277 | }, 278 | keep3: { 279 | type: 'string', 280 | description: 'important stuff', 281 | mathExpression: '' 282 | } 283 | } 284 | }; 285 | 286 | schema = guiUtils.modSchemaForJSONEditor(schema); 287 | 288 | assert.ok(schema.properties.keep); 289 | assert.ok(schema.properties.keep2); 290 | assert.ok(schema.properties.keep3); 291 | assert.strictEqual(schema.properties.remove, undefined); 292 | }); 293 | it('filter_extra_props', function () { 294 | const schema = { 295 | properties: { 296 | foo: { type: 'string' } 297 | } 298 | }; 299 | const view = { 300 | foo: 'bar', 301 | baz: 0 302 | }; 303 | const filteredView = guiUtils.filterExtraProperties(view, schema); 304 | assert.deepStrictEqual(filteredView, { foo: 'bar' }); 305 | 306 | assert.deepStrictEqual(guiUtils.filterExtraProperties(view, {}), {}); 307 | }); 308 | it('filter_extra_props_all_of', function () { 309 | const schema = { 310 | properties: { 311 | foo: { type: 'string' } 312 | }, 313 | allOf: [ 314 | { 315 | properties: { 316 | baz: { type: 'integer' } 317 | } 318 | } 319 | ] 320 | }; 321 | const view = { 322 | foo: 'bar', 323 | baz: 0, 324 | noshow: '' 325 | }; 326 | const filteredView = guiUtils.filterExtraProperties(view, schema); 327 | assert.deepStrictEqual(filteredView, { foo: 'bar', baz: 0 }); 328 | 329 | assert.deepStrictEqual(guiUtils.filterExtraProperties(view, {}), {}); 330 | }); 331 | it('generate_html_preview', function () { 332 | const schema = { 333 | properties: { 334 | foo: { type: 'string' } 335 | } 336 | }; 337 | const view = {}; 338 | const htmlData = guiUtils.generateHtmlPreview(schema, view); 339 | 340 | assert.notStrictEqual(htmlData, ''); 341 | }); 342 | }); 343 | -------------------------------------------------------------------------------- /lib/github_provider.js: -------------------------------------------------------------------------------- 1 | /* Copyright 2021 F5 Networks, Inc. 2 | * 3 | * Licensed under the Apache License, Version 2.0 (the "License"); 4 | * you may not use this file except in compliance with the License. 5 | * You may obtain a copy of the License at 6 | * 7 | * http://www.apache.org/licenses/LICENSE-2.0 8 | * 9 | * Unless required by applicable law or agreed to in writing, software 10 | * distributed under the License is distributed on an "AS IS" BASIS, 11 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | * See the License for the specific language governing permissions and 13 | * limitations under the License. 14 | */ 15 | 16 | 'use strict'; 17 | 18 | const crypto = require('crypto'); 19 | 20 | const axios = require('axios'); 21 | 22 | const Template = require('./template').Template; 23 | const { BaseSchemaProvider } = require('./schema_provider'); 24 | const { BaseDataProvider } = require('./data_provider'); 25 | const { BaseTemplateProvider } = require('./template_provider'); 26 | const { stripExtension } = require('./utils'); 27 | 28 | class GitHubContentsApi { 29 | constructor(repo, options) { 30 | const axiosConfig = { 31 | baseURL: `https://api.github.com/repos/${repo}/contents/` 32 | }; 33 | if (options.apiToken) { 34 | axiosConfig.headers = { 35 | Authorization: `Token ${options.apiToken}` 36 | }; 37 | } 38 | this.endpoint = axios.create(axiosConfig); 39 | } 40 | 41 | _handleResponseError(err, task) { 42 | if (err.response) { 43 | const resp = err.response; 44 | const errStr = `${resp.status}: ${resp.data.message}`; 45 | return Promise.reject(new Error( 46 | `failed to ${task}: ${errStr}` 47 | )); 48 | } 49 | return Promise.reject(err); 50 | } 51 | 52 | getContentsByType(dir, type) { 53 | return Promise.resolve() 54 | .then(() => this.endpoint.get(dir)) 55 | .catch(e => this._handleResponseError(e, `get items for ${dir}`)) 56 | .then(resp => resp.data) 57 | .then(data => data 58 | .filter(x => x.type === type) 59 | .map(x => x.name)); 60 | } 61 | 62 | getContentsData(contentPath) { 63 | return Promise.resolve() 64 | .then(() => this.endpoint(contentPath, { 65 | responseType: 'text', 66 | headers: { 67 | Accept: 'application/vnd.github.v3+raw' 68 | } 69 | })) 70 | .catch(e => this._handleResponseError(e, `get contents for ${contentPath}`)) 71 | .then((resp) => { 72 | if (typeof resp.data === 'string' && !(resp.data.startsWith('{') || resp.data === '')) { 73 | return resp.data; 74 | } 75 | const jsonData = typeof resp.data === 'string' ? JSON.parse(resp.data) : resp.data; 76 | if (!jsonData || !jsonData.content) { 77 | return Promise.reject(new Error(`File not found: ${contentPath}`)); 78 | } 79 | return Buffer.from(jsonData.content, 'base64').toString('utf8'); 80 | }); 81 | } 82 | } 83 | 84 | /** 85 | * SchemaProvider that fetches data from a GitHub repository 86 | */ 87 | class GitHubSchemaProvider extends BaseSchemaProvider { 88 | constructor(repo, schemaRootPath, options) { 89 | super(); 90 | 91 | options = options || {}; 92 | 93 | this._rootDir = `/${schemaRootPath}`; 94 | this._contentsApi = new GitHubContentsApi(repo, { 95 | apiToken: options.apiToken 96 | }); 97 | } 98 | 99 | _loadSchema(schemaName) { 100 | return Promise.resolve() 101 | .then(() => this._contentsApi.getContentsData(`${this._rootDir}/${schemaName}.json`)); 102 | } 103 | 104 | /** 105 | * List all schema known to the provider 106 | * 107 | * @returns {string[]} 108 | */ 109 | list() { 110 | return Promise.resolve() 111 | .then(() => this._contentsApi.getContentsByType(this._rootDir, 'file')) 112 | .then(files => files 113 | .filter(x => x.endsWith('.json')) 114 | .map(x => stripExtension(x))); 115 | } 116 | } 117 | 118 | /** 119 | * DataProvider that fetches data from a GitHub repository 120 | */ 121 | class GitHubDataProvider extends BaseDataProvider { 122 | /** 123 | * @param {string} dataRootPath - a path to a directory containing data files 124 | */ 125 | constructor(repo, dataRootPath, options) { 126 | super(); 127 | options = options || {}; 128 | 129 | this._rootDir = `/${dataRootPath}`; 130 | this._contentsApi = new GitHubContentsApi(repo, { 131 | apiToken: options.apiToken 132 | }); 133 | } 134 | 135 | _loadData(dataName) { 136 | return Promise.resolve() 137 | .then(() => this._contentsApi.getContentsData(`${this._rootDir}/${dataName}.data`)); 138 | } 139 | 140 | /** 141 | * List all data files known to the provider 142 | * 143 | * @returns {string[]} 144 | */ 145 | list() { 146 | return Promise.resolve() 147 | .then(() => this._contentsApi.getContentsByType(this._rootDir, 'file')) 148 | .then(files => files 149 | .filter(x => x.endsWith('.data')) 150 | .map(x => stripExtension(x))); 151 | } 152 | } 153 | 154 | /** 155 | * TemplateProvider that fetches data from a GitHub repository 156 | */ 157 | class GitHubTemplateProvider extends BaseTemplateProvider { 158 | constructor(repo, options) { 159 | options = options || {}; 160 | 161 | super(options.supportedHashes); 162 | 163 | this.filteredSets = new Set(options.filteredSets || []); 164 | 165 | this.repo = repo; 166 | this._apiToken = options.apiToken; 167 | 168 | this._schemaProviders = {}; 169 | this._dataProviders = {}; 170 | 171 | this._contentsApi = new GitHubContentsApi(this.repo, { 172 | apiToken: this._apiToken 173 | }); 174 | } 175 | 176 | _loadTemplate(templatePath) { 177 | const tmplParts = templatePath.split('/'); 178 | const tmplDir = tmplParts.slice(0, -1).join('/'); 179 | const tmplName = tmplParts[tmplParts.length - 1]; 180 | 181 | const schemaProvider = this._getSchemaProvider(tmplDir); 182 | const dataProvider = this._getDataProvider(tmplDir); 183 | return Promise.resolve() 184 | .then(() => this._contentsApi.getContentsByType(tmplDir, 'file')) 185 | .then((files) => { 186 | let useMst = 0; 187 | let fname; 188 | 189 | if (files.includes(`${tmplName}.yml`)) { 190 | fname = `${tmplName}.yml`; 191 | } else if (files.includes(`${tmplName}.yaml`)) { 192 | fname = `${tmplName}.yaml`; 193 | } else if (files.includes(`${tmplName}.mst`)) { 194 | useMst = 1; 195 | fname = `${tmplName}.mst`; 196 | } else { 197 | return Promise.reject(new Error(`could not find a template with name "${templatePath}"`)); 198 | } 199 | 200 | fname = `${tmplDir}/${fname}`; 201 | 202 | return Promise.resolve() 203 | .then(() => this._contentsApi.getContentsData(fname)) 204 | .then(tmpldata => Template[useMst ? 'loadMst' : 'loadYaml'](tmpldata, { 205 | schemaProvider, 206 | dataProvider, 207 | templateProvider: this, 208 | rootDir: tmplDir 209 | })); 210 | }); 211 | } 212 | 213 | _getSchemaProvider(tsName) { 214 | if (!this._schemaProviders[tsName]) { 215 | this._schemaProviders[tsName] = new GitHubSchemaProvider(this.repo, tsName, { apiToken: this._apiToken }); 216 | } 217 | 218 | return this._schemaProviders[tsName]; 219 | } 220 | 221 | _getDataProvider(tsName) { 222 | if (!this._dataProviders[tsName]) { 223 | this._dataProviders[tsName] = new GitHubDataProvider(this.repo, tsName, { apiToken: this._apiToken }); 224 | } 225 | 226 | return this._dataProviders[tsName]; 227 | } 228 | 229 | /** 230 | * Get a list of set names known to the provider 231 | * 232 | * @returns {Promise} Promise resolves to a string array 233 | */ 234 | listSets() { 235 | return Promise.resolve() 236 | .then(() => this._contentsApi.getContentsByType('', 'dir')) 237 | .then(items => items.filter( 238 | x => this.filteredSets.size === 0 || this.filteredSets.has(x) 239 | )); 240 | } 241 | 242 | /** 243 | * List all templates known to the provider (optionally filtered by the supplied list of set names) 244 | * 245 | * @param {string[]} [setList=[]] 246 | * @returns {Promise} Promise resolves to a string array 247 | */ 248 | list(setList) { 249 | setList = setList || []; 250 | if (typeof setList === 'string') { 251 | setList = [setList]; 252 | } 253 | 254 | return this.listSets() 255 | .then(sets => sets.filter(x => setList.length === 0 || setList.includes(x))) 256 | .then(sets => Promise.all(sets.map( 257 | setName => this._contentsApi.getContentsByType(`/${setName}`, 'file') 258 | .then(data => data 259 | .filter(x => this.hasTemplateExtension(x)) 260 | .map(x => `${setName}/${stripExtension(x)}`)) 261 | ))) 262 | .then(sets => sets.reduce((acc, curr) => acc.concat(curr), [])); 263 | } 264 | 265 | /** 266 | * Delete the template set associated with the supplied set ID. 267 | * 268 | * Not implemented for FsSchemaProvider. 269 | * 270 | * @returns {Promise} 271 | */ 272 | removeSet() { 273 | return Promise.reject(new Error('Set removal not implemented')); 274 | } 275 | 276 | /** 277 | * Get all schema known to the provider (optionally filtered by the supplied set name) 278 | * 279 | * @param {string} [filteredSetName] - only return data for this template set (instead of all template sets) 280 | * @returns {Promise} Promise resolves to an object containing schema 281 | */ 282 | getSchemas(filteredSetName) { 283 | const schemas = {}; 284 | return Promise.resolve() 285 | .then(() => (filteredSetName ? [filteredSetName] : this.listSets())) 286 | .then(setList => Promise.all(setList.map( 287 | tsName => this._getSchemaProvider(tsName).list() 288 | .then(schemaList => Promise.all(schemaList.map( 289 | schemaName => this._getSchemaProvider(tsName).fetch(schemaName) 290 | .then((schemaData) => { 291 | const name = `${tsName}/${schemaName}`; 292 | const schemaHash = crypto.createHash('sha256'); 293 | schemaHash.update(schemaData); 294 | schemas[name] = { 295 | name, 296 | data: schemaData, 297 | hash: schemaHash.digest('hex') 298 | }; 299 | }) 300 | ))) 301 | ))) 302 | .then(() => schemas); 303 | } 304 | 305 | /** 306 | * Get all data files known to the provider (optionally filtered by the supplied set name) 307 | * 308 | * @param {string} [filteredSetName] - only return data for this template set (instead of all template sets) 309 | * @returns {Promise} Promise resolves to an object containing data files 310 | */ 311 | getDataFiles(filteredSetName) { 312 | const dataFiles = {}; 313 | return Promise.resolve() 314 | .then(() => (filteredSetName ? [filteredSetName] : this.listSets())) 315 | .then(setList => Promise.all(setList.map( 316 | tsName => this._getDataProvider(tsName).list() 317 | .then(dataFileList => Promise.all(dataFileList.map( 318 | dataName => this._getDataProvider(tsName).fetch(dataName) 319 | .then((data) => { 320 | const name = `${tsName}/${dataName}`; 321 | const dataHash = crypto.createHash('sha256'); 322 | dataHash.update(data); 323 | dataFiles[name] = { 324 | name, 325 | data, 326 | hash: dataHash.digest('hex') 327 | }; 328 | }) 329 | ))) 330 | ))) 331 | .then(() => dataFiles); 332 | } 333 | } 334 | 335 | module.exports = { 336 | GitHubTemplateProvider, 337 | GitHubSchemaProvider 338 | }; 339 | -------------------------------------------------------------------------------- /cli.js: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env node 2 | 3 | /* Copyright 2021 F5 Networks, Inc. 4 | * 5 | * Licensed under the Apache License, Version 2.0 (the "License"); 6 | * you may not use this file except in compliance with the License. 7 | * You may obtain a copy of the License at 8 | * 9 | * http://www.apache.org/licenses/LICENSE-2.0 10 | * 11 | * Unless required by applicable law or agreed to in writing, software 12 | * distributed under the License is distributed on an "AS IS" BASIS, 13 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 | * See the License for the specific language governing permissions and 15 | * limitations under the License. 16 | */ 17 | 18 | 'use strict'; 19 | 20 | const fs = require('fs').promises; 21 | const path = require('path'); 22 | const yaml = require('js-yaml'); 23 | 24 | const FsTemplateProvider = require('./lib/template_provider').FsTemplateProvider; 25 | const guiUtils = require('./lib/gui_utils'); 26 | 27 | let logger = null; 28 | const setLogger = (argv) => { 29 | const jsonOutput = argv.jsonOutput; 30 | 31 | if (jsonOutput) { 32 | logger = { 33 | isJSON: true, 34 | output: {}, 35 | log: (msg) => { 36 | if (typeof logger.output.result === 'undefined') { 37 | logger.output.result = msg; 38 | } else { 39 | logger.output.result += `\n${msg}`; 40 | } 41 | }, 42 | error: (msg) => { 43 | if (typeof logger.output.error === 'undefined') { 44 | logger.output.error = msg; 45 | } else { 46 | logger.output.error += `\n${msg}`; 47 | } 48 | } 49 | }; 50 | process.on('exit', () => { 51 | if (typeof logger.output.error === 'undefined' 52 | && typeof logger.output.result === 'undefined') { 53 | logger.output.result = ''; 54 | } 55 | const msg = JSON.stringify(logger.output); 56 | console.log(msg); // eslint-disable-line no-console 57 | }); 58 | } else { 59 | logger = { 60 | isJSON: false, 61 | log: (msg) => { 62 | if (typeof msg === 'object') { 63 | msg = JSON.stringify(msg, null, 2); 64 | } 65 | console.log(msg); // eslint-disable-line no-console 66 | }, 67 | error: (msg) => { 68 | if (typeof msg === 'object') { 69 | msg = JSON.stringify(msg, null, 2); 70 | } 71 | console.error(msg); // eslint-disable-line no-console 72 | } 73 | }; 74 | } 75 | }; 76 | 77 | const loadTemplate = (templatePath) => { 78 | const tmplName = path.basename(templatePath, path.extname(templatePath)); 79 | const tsName = path.basename(path.dirname(templatePath)); 80 | const tsDir = path.dirname(path.dirname(templatePath)); 81 | const provider = new FsTemplateProvider(tsDir, [tsName]); 82 | return provider.fetch(`${tsName}/${tmplName}`) 83 | .catch((e) => { 84 | const validationErrors = e.validationErrors; 85 | const errMsg = (validationErrors) ? 'template failed validation' : e.message; 86 | logger.error(`failed to load template: ${errMsg}`); 87 | if (validationErrors) { 88 | if (logger.isJSON) { 89 | logger.output.validationErrors = validationErrors; 90 | } else { 91 | logger.error('validation errors:'); 92 | logger.error(validationErrors); 93 | } 94 | } 95 | process.exit(1); 96 | }); 97 | }; 98 | 99 | const loadParameters = (parametersPath) => { 100 | if (!parametersPath) return Promise.resolve({}); 101 | return fs.readFile(parametersPath, 'utf8') 102 | .then(paramsData => yaml.load(paramsData)) 103 | .catch((e) => { 104 | logger.error(`Failed to load the parameters file:\n${e.stack}`); 105 | process.exit(1); 106 | }); 107 | }; 108 | 109 | const loadTemplateAndParameters = (templatePath, parametersPath) => Promise.all([ 110 | loadTemplate(templatePath), 111 | loadParameters(parametersPath) 112 | ]); 113 | 114 | const validateTemplate = templatePath => loadTemplate(templatePath) 115 | .then(() => { 116 | logger.log(`template source at ${templatePath} is valid`); 117 | }); 118 | 119 | const templateToParametersSchema = templatePath => loadTemplate(templatePath) 120 | .then((tmpl) => { 121 | const schema = tmpl.getParametersSchema(); 122 | logger.log(schema); 123 | }) 124 | .catch((e) => { 125 | logger.error(`Failed to generate schema:\n${e.stack}`); 126 | process.exit(1); 127 | }); 128 | 129 | const templateToParametersSchemaGui = templatePath => loadTemplate(templatePath) 130 | .then((tmpl) => { 131 | let schema = tmpl.getParametersSchema(); 132 | schema = guiUtils.modSchemaForJSONEditor(schema); 133 | logger.log(schema); 134 | }) 135 | .catch((e) => { 136 | logger.error(`Failed to generate schema:\n${e.stack}`); 137 | process.exit(1); 138 | }); 139 | 140 | const validateParameters = (templatePath, parametersPath) => loadTemplateAndParameters(templatePath, parametersPath) 141 | .then(([tmpl, parameters]) => { 142 | tmpl.validateParameters(parameters); 143 | }) 144 | .catch((e) => { 145 | if (e.validationErrors) { 146 | logger.error('parameters failed validation'); 147 | if (logger.isJSON) { 148 | logger.output.templateParameters = e.parameters; 149 | logger.output.validationErrors = e.validationErrors; 150 | } else { 151 | logger.error(JSON.stringify(e.validationErrors, null, 2)); 152 | logger.error(`\nSupplied parameters:\n${JSON.stringify(e.parameters, null, 2)}`); 153 | } 154 | } else { 155 | logger.error(`parameters failed validation: ${e.stack}`); 156 | } 157 | process.exit(1); 158 | }); 159 | 160 | const renderTemplate = (templatePath, parametersPath) => loadTemplateAndParameters(templatePath, parametersPath) 161 | .then(([tmpl, parameters]) => Promise.all([ 162 | Promise.resolve(tmpl), 163 | tmpl.fetchHttp() 164 | .then(httpParams => Object.assign({}, parameters, httpParams)) 165 | ])) 166 | .then(([tmpl, parameters]) => { 167 | logger.log(tmpl.render(parameters)); 168 | }) 169 | .catch((e) => { 170 | if (e.validationErrors) { 171 | logger.error('Failed to render template since parameters failed validation'); 172 | if (logger.isJSON) { 173 | logger.output.templateParameters = e.parameters; 174 | logger.output.validationErrors = e.validationErrors; 175 | } else { 176 | logger.error(JSON.stringify(e.validationErrors, null, 2)); 177 | logger.error(`\nSupplied parameters:\n${JSON.stringify(e.parameters, null, 2)}`); 178 | } 179 | } else { 180 | logger.error(`Failed to render template:\n${e.stack}`); 181 | } 182 | process.exit(1); 183 | }); 184 | 185 | const validateTemplateSet = (tsPath) => { 186 | const tsName = path.basename(tsPath); 187 | const tsDir = path.dirname(tsPath); 188 | const provider = new FsTemplateProvider(tsDir, [tsName]); 189 | let errorFound = false; 190 | return provider.list() 191 | .then(templateList => Promise.all( 192 | templateList.map( 193 | tmpl => provider.fetch(tmpl) 194 | .catch((e) => { 195 | const validationErrors = e.validationErrors; 196 | const errMsg = `Template ${tmpl} failed validation: ${e.message}`; 197 | if (validationErrors) { 198 | if (logger.isJSON) { 199 | if (!logger.output.errors) { 200 | logger.output.errors = []; 201 | } 202 | logger.output.errors.push({ 203 | message: errMsg, 204 | validationErrors 205 | }); 206 | } else { 207 | logger.error(errMsg); 208 | logger.error(validationErrors); 209 | } 210 | } 211 | errorFound = true; 212 | }) 213 | 214 | ) 215 | )) 216 | .then(() => { 217 | if (errorFound) { 218 | logger.error(`Template set "${tsName}" failed validation`); 219 | process.exit(1); 220 | } 221 | }) 222 | .catch((e) => { 223 | logger.error(`Template set "${tsName}" failed validation:\n${e.stack}`); 224 | process.exit(1); 225 | }); 226 | }; 227 | 228 | const htmlPreview = (templatePath, parametersPath) => loadTemplateAndParameters(templatePath, parametersPath) 229 | .then(([tmpl, parameters]) => guiUtils.generateHtmlPreview( 230 | tmpl.getParametersSchema(), 231 | tmpl.getCombinedParameters(parameters) 232 | )) 233 | .then(htmlData => logger.log(htmlData)); 234 | 235 | const packageTemplateSet = (tsPath, dst) => validateTemplateSet(tsPath) 236 | .then(() => { 237 | const tsName = path.basename(tsPath); 238 | const tsDir = path.dirname(tsPath); 239 | const provider = new FsTemplateProvider(tsDir, [tsName]); 240 | 241 | dst = dst || `./${tsName}.zip`; 242 | 243 | return provider.buildPackage(tsName, dst) 244 | .then(() => { 245 | logger.log(`Template set "${tsName}" packaged as ${dst}`); 246 | }); 247 | }); 248 | 249 | /* eslint-disable-next-line no-unused-expressions */ 250 | require('yargs') 251 | .option('json-output', { 252 | describe: 'output JSON instead of plain text', 253 | type: 'boolean' 254 | }) 255 | .command('validate ', 'validate given template source file', (yargs) => { 256 | yargs 257 | .positional('file', { 258 | describe: 'template source file to validate' 259 | }); 260 | }, argv => validateTemplate(argv.file)) 261 | .command('schema ', 'get template parameter schema for given template source file', (yargs) => { 262 | yargs 263 | .positional('file', { 264 | describe: 'template source file to parse' 265 | }); 266 | }, argv => templateToParametersSchema(argv.file)) 267 | .command('guiSchema ', 'get template parameter schema (modified for use with JSON Editor) for given template source file', (yargs) => { 268 | yargs 269 | .positional('file', { 270 | describe: 'template source file to parse' 271 | }); 272 | }, argv => templateToParametersSchemaGui(argv.file)) 273 | .command('validateParameters ', 'validate supplied template parameters with given template', (yargs) => { 274 | yargs 275 | .positional('tmplFile', { 276 | describe: 'template to get template parameters schema from' 277 | }) 278 | .positional('parameterFile', { 279 | describe: 'file with template parameters to validate' 280 | }); 281 | }, argv => validateParameters(argv.tmplFile, argv.parameterFile)) 282 | .command('render [parameterFile]', 'render given template file with supplied parameters', (yargs) => { 283 | yargs 284 | .positional('tmplFile', { 285 | describe: 'template source file to render' 286 | }) 287 | .positional('parameterFile', { 288 | describe: 'optional file with template parameters to use in addition to any defined in the parameters in the template source file' 289 | }); 290 | }, argv => renderTemplate(argv.tmplFile, argv.parameterFile)) 291 | .command('validateTemplateSet ', 'validate supplied template set', (yargs) => { 292 | yargs 293 | .positional('templateSetPath', { 294 | describe: 'path to the directory containing template sources' 295 | }); 296 | }, argv => validateTemplateSet(argv.templateSetPath)) 297 | .command('htmlpreview [parameterFile]', 'generate a static HTML file with a preview editor to standard out', (yargs) => { 298 | yargs 299 | .positional('tmplFile', { 300 | describe: 'template source file to render' 301 | }) 302 | .positional('parameterFile', { 303 | describe: 'optional file with template parameters to use in addition to any defined in the parameters in the template source file' 304 | }); 305 | }, argv => htmlPreview(argv.tmplFile, argv.parameterFile)) 306 | .command('packageTemplateSet [dst]', 'build a package for a given template set', (yargs) => { 307 | yargs 308 | .positional('templateSetPath', { 309 | describe: 'path to the directory containing template sources' 310 | }) 311 | .positional('dst', { 312 | describe: 'optional location for the built package (defaults to the current working directory)' 313 | }); 314 | }, argv => packageTemplateSet(argv.templateSetPath, argv.dst)) 315 | .demandCommand(1, 'A command is required') 316 | .wrap(120) 317 | .strict() 318 | .middleware([setLogger]) 319 | .argv; 320 | -------------------------------------------------------------------------------- /test/cli.js: -------------------------------------------------------------------------------- 1 | /* Copyright 2021 F5 Networks, Inc. 2 | * 3 | * Licensed under the Apache License, Version 2.0 (the "License"); 4 | * you may not use this file except in compliance with the License. 5 | * You may obtain a copy of the License at 6 | * 7 | * http://www.apache.org/licenses/LICENSE-2.0 8 | * 9 | * Unless required by applicable law or agreed to in writing, software 10 | * distributed under the License is distributed on an "AS IS" BASIS, 11 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 | * See the License for the specific language governing permissions and 13 | * limitations under the License. 14 | */ 15 | 16 | /* eslint-disable prefer-arrow-callback */ 17 | /* eslint-disable func-names */ 18 | /* eslint-disable no-console */ 19 | 20 | 'use strict'; 21 | 22 | const { exec } = require('child_process'); 23 | const path = require('path'); 24 | const os = require('os'); 25 | const fs = require('fs'); 26 | const assert = require('assert'); 27 | 28 | const templateSetDir = path.join(__dirname, 'templatesets', 'test'); 29 | const templateSimplePath = path.join(templateSetDir, 'simple.yaml'); 30 | 31 | async function executeCommand(commandStr) { 32 | const cmd = `node ${path.join('..', 'cli.js')} ${commandStr}`; 33 | console.log(`running: ${cmd}`); 34 | return new Promise((resolve, reject) => { 35 | exec(cmd, { cwd: __dirname }, (error, stdout, stderr) => { 36 | if (error) { 37 | error.stdout = stdout; 38 | error.stderr = stderr; 39 | reject(error); 40 | } 41 | 42 | resolve({ stdout, stderr }); 43 | }); 44 | }); 45 | } 46 | 47 | describe('CLI tests', function () { 48 | let tmpDir = null; 49 | const mktmpdir = () => { 50 | tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'fast')); 51 | }; 52 | 53 | const rmtmpdir = () => { 54 | if (tmpDir !== null) { 55 | if (fs.rmSync) { 56 | fs.rmSync(tmpDir, { recursive: true }); 57 | } else { 58 | // Older Node version 59 | fs.rmdirSync(tmpDir, { recursive: true }); 60 | } 61 | tmpDir = null; 62 | } 63 | }; 64 | 65 | afterEach(rmtmpdir); 66 | 67 | describe('validate', function () { 68 | it('should succeed on valid template', async function () { 69 | const { stdout } = await executeCommand(`validate ${templateSimplePath}`); 70 | assert.match(stdout, /template source at .* is valid/); 71 | }); 72 | it('should fail on invalid template', async function () { 73 | const invalidTemplatePath = path.join(__dirname, 'invalid_templatesets', 'invalid', 'invalid.yaml'); 74 | return executeCommand(`validate ${invalidTemplatePath}`) 75 | .then(() => assert(false, 'Expected command to fail')) 76 | .catch((e) => { 77 | console.log(e); 78 | assert.match(e.stderr, /failed to load template/); 79 | }); 80 | }); 81 | it('should support JSON output', async function () { 82 | const { stdout } = await executeCommand(`validate --json-output ${templateSimplePath}`); 83 | const output = JSON.parse(stdout); 84 | assert.match(output.result, /template source at .* is valid/); 85 | }); 86 | it('should support JSON error output', async function () { 87 | const invalidTemplatePath = path.join(__dirname, 'invalid_templatesets', 'invalid', 'invalid.yaml'); 88 | return executeCommand(`validate --json-output ${invalidTemplatePath}`) 89 | .then(() => assert(false, 'Expected command to fail')) 90 | .catch((e) => { 91 | const output = JSON.parse(e.stdout); 92 | console.log(output); 93 | assert.match(output.error, /failed to load template/); 94 | }); 95 | }); 96 | }); 97 | describe('schema', function () { 98 | it('should output template parameters schema', async function () { 99 | const { stdout } = await executeCommand(`schema ${templateSimplePath}`); 100 | const schema = JSON.parse(stdout); 101 | assert.ok(schema.properties.str_var); 102 | assert.match(schema.title, /Simple YAML file/); 103 | }); 104 | it('should support JSON output', async function () { 105 | const { stdout } = await executeCommand(`schema --json-output ${templateSimplePath}`); 106 | const output = JSON.parse(stdout); 107 | const schema = output.result; 108 | assert.ok(schema.properties.str_var); 109 | assert.match(schema.title, /Simple YAML file/); 110 | }); 111 | }); 112 | describe('guiSchema', function () { 113 | it('should output gui-friendly template parameters schema', async function () { 114 | const { stdout } = await executeCommand(`guiSchema ${templateSimplePath}`); 115 | const schema = JSON.parse(stdout); 116 | assert.ok(schema.properties.str_var); 117 | assert.match(schema.title, /Simple YAML file/); 118 | }); 119 | it('should support JSON output', async function () { 120 | const { stdout } = await executeCommand(`guiSchema --json-output ${templateSimplePath}`); 121 | const output = JSON.parse(stdout); 122 | const schema = output.result; 123 | assert.ok(schema.properties.str_var); 124 | assert.match(schema.title, /Simple YAML file/); 125 | }); 126 | }); 127 | describe('validateParameters', function () { 128 | it('should succeed on valid parameters', async function () { 129 | mktmpdir(); 130 | const viewPath = path.join(tmpDir, 'view.json'); 131 | fs.writeFileSync(viewPath, JSON.stringify({ str_var: 'bar' })); 132 | const { stdout } = await executeCommand(`validateParameters ${templateSimplePath} ${viewPath}`); 133 | assert.strictEqual(stdout, ''); 134 | }); 135 | it('should fail on invalid parameters', async function () { 136 | mktmpdir(); 137 | const viewPath = path.join(tmpDir, 'view.json'); 138 | fs.writeFileSync(viewPath, JSON.stringify({ str_var: 5 })); 139 | return executeCommand(`validateParameters ${templateSimplePath} ${viewPath}`) 140 | .then(() => assert(false, 'Expected command to fail')) 141 | .catch((e) => { 142 | console.log(e); 143 | assert.match(e.stderr, /parameters failed validation/); 144 | }); 145 | }); 146 | it('should support JSON output', async function () { 147 | mktmpdir(); 148 | const viewPath = path.join(tmpDir, 'view.json'); 149 | fs.writeFileSync(viewPath, JSON.stringify({ str_var: 'bar' })); 150 | const { stdout } = await executeCommand(`validateParameters --json-output ${templateSimplePath} ${viewPath}`); 151 | const output = JSON.parse(stdout); 152 | assert.strictEqual(output.result, ''); 153 | }); 154 | it('should support JSON error output', async function () { 155 | mktmpdir(); 156 | const viewPath = path.join(tmpDir, 'view.json'); 157 | fs.writeFileSync(viewPath, JSON.stringify({ str_var: 5 })); 158 | return executeCommand(`validateParameters --json-output ${templateSimplePath} ${viewPath}`) 159 | .then(() => assert(false, 'Expected command to fail')) 160 | .catch((e) => { 161 | const output = JSON.parse(e.stdout); 162 | console.log(output); 163 | assert.match(output.error, /parameters failed validation/); 164 | assert.deepStrictEqual( 165 | output.templateParameters, 166 | { 167 | str_var: 5 168 | } 169 | ); 170 | assert.deepStrictEqual( 171 | output.validationErrors, 172 | [ 173 | { message: 'parameter str_var should be of type string' } 174 | ] 175 | ); 176 | }); 177 | }); 178 | }); 179 | describe('render', function () { 180 | it('should render template to stdout', async function () { 181 | const { stdout } = await executeCommand(`render ${templateSimplePath}`); 182 | assert.match(stdout, /foo/); 183 | }); 184 | it('should fail on invalid parameters', async function () { 185 | mktmpdir(); 186 | const viewPath = path.join(tmpDir, 'view.json'); 187 | fs.writeFileSync(viewPath, JSON.stringify({ str_var: 5 })); 188 | return executeCommand(`render ${templateSimplePath} ${viewPath}`) 189 | .then(() => assert(false, 'Expected command to fail')) 190 | .catch((e) => { 191 | console.log(e); 192 | assert.match(e.stderr, /Failed to render template since parameters failed validation/); 193 | }); 194 | }); 195 | it('should support JSON output', async function () { 196 | const { stdout } = await executeCommand(`render --json-output ${templateSimplePath}`); 197 | const output = JSON.parse(stdout); 198 | assert.match(output.result, /foo/); 199 | }); 200 | it('should support JSON error output', async function () { 201 | mktmpdir(); 202 | const viewPath = path.join(tmpDir, 'view.json'); 203 | fs.writeFileSync(viewPath, JSON.stringify({ str_var: 5 })); 204 | return executeCommand(`render --json-output ${templateSimplePath} ${viewPath}`) 205 | .then(() => assert(false, 'Expected command to fail')) 206 | .catch((e) => { 207 | const output = JSON.parse(e.stdout); 208 | console.log(output); 209 | assert.match(output.error, /parameters failed validation/); 210 | assert.deepStrictEqual( 211 | output.templateParameters, 212 | { 213 | str_var: 5 214 | } 215 | ); 216 | assert.deepStrictEqual( 217 | output.validationErrors, 218 | [ 219 | { message: 'parameter str_var should be of type string' } 220 | ] 221 | ); 222 | }); 223 | }); 224 | }); 225 | describe('validateTemplateSet', function () { 226 | it('should succeed on valid template set', async function () { 227 | const { stdout } = await executeCommand(`validateTemplateSet ${templateSetDir}`); 228 | assert.strictEqual(stdout, ''); 229 | }); 230 | it('should fail on invalid template set', async function () { 231 | const invalidSetPath = path.join(__dirname, 'invalid_templatesets', 'invalid'); 232 | return executeCommand(`validateTemplateSet ${invalidSetPath}`) 233 | .then(() => assert(false, 'Expected command to fail')) 234 | .catch((e) => { 235 | console.log(e); 236 | assert.match(e.stderr, /Template .* failed validation/); 237 | }); 238 | }); 239 | it('should support JSON output', async function () { 240 | const { stdout } = await executeCommand(`validateTemplateSet --json-output ${templateSetDir}`); 241 | const output = JSON.parse(stdout); 242 | assert.strictEqual(output.result, ''); 243 | }); 244 | it('should support JSON error output', async function () { 245 | const invalidSetPath = path.join(__dirname, 'invalid_templatesets', 'invalid'); 246 | return executeCommand(`validateTemplateSet --json-output ${invalidSetPath}`) 247 | .then(() => assert(false, 'Expected command to fail')) 248 | .catch((e) => { 249 | const output = JSON.parse(e.stdout); 250 | console.log(output); 251 | assert.match(output.error, /Template set .* failed validation/); 252 | assert.match(output.errors[0].message, /Template .* failed validation/); 253 | assert.match(output.errors[0].validationErrors[0].message, /invalid template text/); 254 | }); 255 | }); 256 | }); 257 | describe('htmlpreview', function () { 258 | it('should generate a static HTML page to stdout', async function () { 259 | const { stdout } = await executeCommand(`htmlpreview ${templateSimplePath}`); 260 | assert.match(stdout, /doctype html/); 261 | }); 262 | it('should support JSON output', async function () { 263 | const { stdout } = await executeCommand(`htmlpreview --json-output ${templateSimplePath}`); 264 | const output = JSON.parse(stdout); 265 | assert.match(output.result, /doctype html/); 266 | }); 267 | }); 268 | describe('packageTemplateSet', function () { 269 | it('should create a package for the given template set', async function () { 270 | mktmpdir(); 271 | const pkgpath = path.join(tmpDir, 'pkg.zip'); 272 | const { stdout } = await executeCommand(`packageTemplateSet ${templateSetDir} ${pkgpath}`); 273 | assert.match(stdout, /Template set "test" packaged as .*\/pkg.zip/); 274 | }); 275 | it('should support JSON output', async function () { 276 | mktmpdir(); 277 | const pkgpath = path.join(tmpDir, 'pkg.zip'); 278 | const { stdout } = await executeCommand(`packageTemplateSet --json-output ${templateSetDir} ${pkgpath}`); 279 | const output = JSON.parse(stdout); 280 | assert.match(output.result, /Template set "test" packaged as .*\/pkg.zip/); 281 | }); 282 | }); 283 | }); 284 | -------------------------------------------------------------------------------- /lib/jsonpath-plus/jsonpath.js: -------------------------------------------------------------------------------- 1 | /* eslint-disable camelcase -- Convenient for escaping */ 2 | 3 | import {SafeScript} from './Safe-Script.js'; 4 | 5 | /** 6 | * @typedef {null|boolean|number|string|object|GenericArray} JSONObject 7 | */ 8 | 9 | /** 10 | * @typedef {any} AnyItem 11 | */ 12 | 13 | /** 14 | * @typedef {any} AnyResult 15 | */ 16 | 17 | /** 18 | * Copies array and then pushes item into it. 19 | * @param {GenericArray} arr Array to copy and into which to push 20 | * @param {AnyItem} item Array item to add (to end) 21 | * @returns {GenericArray} Copy of the original array 22 | */ 23 | function push (arr, item) { 24 | arr = arr.slice(); 25 | arr.push(item); 26 | return arr; 27 | } 28 | /** 29 | * Copies array and then unshifts item into it. 30 | * @param {AnyItem} item Array item to add (to beginning) 31 | * @param {GenericArray} arr Array to copy and into which to unshift 32 | * @returns {GenericArray} Copy of the original array 33 | */ 34 | function unshift (item, arr) { 35 | arr = arr.slice(); 36 | arr.unshift(item); 37 | return arr; 38 | } 39 | 40 | /** 41 | * Caught when JSONPath is used without `new` but rethrown if with `new` 42 | * @extends Error 43 | */ 44 | class NewError extends Error { 45 | /** 46 | * @param {AnyResult} value The evaluated scalar value 47 | */ 48 | constructor (value) { 49 | super( 50 | 'JSONPath should not be called with "new" (it prevents return ' + 51 | 'of (unwrapped) scalar values)' 52 | ); 53 | this.avoidNew = true; 54 | this.value = value; 55 | this.name = 'NewError'; 56 | } 57 | } 58 | 59 | /** 60 | * @typedef {object} ReturnObject 61 | * @property {string} path 62 | * @property {JSONObject} value 63 | * @property {object|GenericArray} parent 64 | * @property {string} parentProperty 65 | */ 66 | 67 | /** 68 | * @callback JSONPathCallback 69 | * @param {string|object} preferredOutput 70 | * @param {"value"|"property"} type 71 | * @param {ReturnObject} fullRetObj 72 | * @returns {void} 73 | */ 74 | 75 | /** 76 | * @callback OtherTypeCallback 77 | * @param {JSONObject} val 78 | * @param {string} path 79 | * @param {object|GenericArray} parent 80 | * @param {string} parentPropName 81 | * @returns {boolean} 82 | */ 83 | 84 | /** 85 | * @typedef {any} ContextItem 86 | */ 87 | 88 | /** 89 | * @typedef {any} EvaluatedResult 90 | */ 91 | 92 | /** 93 | * @callback EvalCallback 94 | * @param {string} code 95 | * @param {ContextItem} context 96 | * @returns {EvaluatedResult} 97 | */ 98 | 99 | /** 100 | * @typedef {typeof SafeScript} EvalClass 101 | */ 102 | 103 | /** 104 | * @typedef {object} JSONPathOptions 105 | * @property {JSON} json 106 | * @property {string|string[]} path 107 | * @property {"value"|"path"|"pointer"|"parent"|"parentProperty"| 108 | * "all"} [resultType="value"] 109 | * @property {boolean} [flatten=false] 110 | * @property {boolean} [wrap=true] 111 | * @property {object} [sandbox={}] 112 | * @property {EvalCallback|EvalClass|'safe'|'native'| 113 | * boolean} [eval = 'safe'] 114 | * @property {object|GenericArray|null} [parent=null] 115 | * @property {string|null} [parentProperty=null] 116 | * @property {JSONPathCallback} [callback] 117 | * @property {OtherTypeCallback} [otherTypeCallback] Defaults to 118 | * function which throws on encountering `@other` 119 | * @property {boolean} [autostart=true] 120 | */ 121 | 122 | /** 123 | * @param {string|JSONPathOptions} opts If a string, will be treated as `expr` 124 | * @param {string} [expr] JSON path to evaluate 125 | * @param {JSON} [obj] JSON object to evaluate against 126 | * @param {JSONPathCallback} [callback] Passed 3 arguments: 1) desired payload 127 | * per `resultType`, 2) `"value"|"property"`, 3) Full returned object with 128 | * all payloads 129 | * @param {OtherTypeCallback} [otherTypeCallback] If `@other()` is at the end 130 | * of one's query, this will be invoked with the value of the item, its 131 | * path, its parent, and its parent's property name, and it should return 132 | * a boolean indicating whether the supplied value belongs to the "other" 133 | * type or not (or it may handle transformations and return `false`). 134 | * @returns {JSONPath} 135 | * @class 136 | */ 137 | function JSONPath (opts, expr, obj, callback, otherTypeCallback) { 138 | // eslint-disable-next-line no-restricted-syntax -- Allow for pseudo-class 139 | if (!(this instanceof JSONPath)) { 140 | try { 141 | return new JSONPath(opts, expr, obj, callback, otherTypeCallback); 142 | } catch (e) { 143 | if (!e.avoidNew) { 144 | throw e; 145 | } 146 | return e.value; 147 | } 148 | } 149 | 150 | if (typeof opts === 'string') { 151 | otherTypeCallback = callback; 152 | callback = obj; 153 | obj = expr; 154 | expr = opts; 155 | opts = null; 156 | } 157 | const optObj = opts && typeof opts === 'object'; 158 | opts = opts || {}; 159 | this.json = opts.json || obj; 160 | this.path = opts.path || expr; 161 | this.resultType = opts.resultType || 'value'; 162 | this.flatten = opts.flatten || false; 163 | this.wrap = Object.hasOwn(opts, 'wrap') ? opts.wrap : true; 164 | this.sandbox = opts.sandbox || {}; 165 | this.eval = opts.eval === undefined ? 'safe' : opts.eval; 166 | this.ignoreEvalErrors = (typeof opts.ignoreEvalErrors === 'undefined') 167 | ? false 168 | : opts.ignoreEvalErrors; 169 | this.parent = opts.parent || null; 170 | this.parentProperty = opts.parentProperty || null; 171 | this.callback = opts.callback || callback || null; 172 | this.otherTypeCallback = opts.otherTypeCallback || 173 | otherTypeCallback || 174 | function () { 175 | throw new TypeError( 176 | 'You must supply an otherTypeCallback callback option ' + 177 | 'with the @other() operator.' 178 | ); 179 | }; 180 | 181 | if (opts.autostart !== false) { 182 | const args = { 183 | path: (optObj ? opts.path : expr) 184 | }; 185 | if (!optObj) { 186 | args.json = obj; 187 | } else if ('json' in opts) { 188 | args.json = opts.json; 189 | } 190 | const ret = this.evaluate(args); 191 | if (!ret || typeof ret !== 'object') { 192 | throw new NewError(ret); 193 | } 194 | return ret; 195 | } 196 | } 197 | 198 | // PUBLIC METHODS 199 | JSONPath.prototype.evaluate = function ( 200 | expr, json, callback, otherTypeCallback 201 | ) { 202 | let currParent = this.parent, 203 | currParentProperty = this.parentProperty; 204 | let {flatten, wrap} = this; 205 | 206 | this.currResultType = this.resultType; 207 | this.currEval = this.eval; 208 | this.currSandbox = this.sandbox; 209 | callback = callback || this.callback; 210 | this.currOtherTypeCallback = otherTypeCallback || this.otherTypeCallback; 211 | 212 | json = json || this.json; 213 | expr = expr || this.path; 214 | if (expr && typeof expr === 'object' && !Array.isArray(expr)) { 215 | if (!expr.path && expr.path !== '') { 216 | throw new TypeError( 217 | 'You must supply a "path" property when providing an object ' + 218 | 'argument to JSONPath.evaluate().' 219 | ); 220 | } 221 | if (!(Object.hasOwn(expr, 'json'))) { 222 | throw new TypeError( 223 | 'You must supply a "json" property when providing an object ' + 224 | 'argument to JSONPath.evaluate().' 225 | ); 226 | } 227 | ({json} = expr); 228 | flatten = Object.hasOwn(expr, 'flatten') ? expr.flatten : flatten; 229 | this.currResultType = Object.hasOwn(expr, 'resultType') 230 | ? expr.resultType 231 | : this.currResultType; 232 | this.currSandbox = Object.hasOwn(expr, 'sandbox') 233 | ? expr.sandbox 234 | : this.currSandbox; 235 | wrap = Object.hasOwn(expr, 'wrap') ? expr.wrap : wrap; 236 | this.currEval = Object.hasOwn(expr, 'eval') 237 | ? expr.eval 238 | : this.currEval; 239 | callback = Object.hasOwn(expr, 'callback') ? expr.callback : callback; 240 | this.currOtherTypeCallback = Object.hasOwn(expr, 'otherTypeCallback') 241 | ? expr.otherTypeCallback 242 | : this.currOtherTypeCallback; 243 | currParent = Object.hasOwn(expr, 'parent') ? expr.parent : currParent; 244 | currParentProperty = Object.hasOwn(expr, 'parentProperty') 245 | ? expr.parentProperty 246 | : currParentProperty; 247 | expr = expr.path; 248 | } 249 | currParent = currParent || null; 250 | currParentProperty = currParentProperty || null; 251 | 252 | if (Array.isArray(expr)) { 253 | expr = JSONPath.toPathString(expr); 254 | } 255 | if ((!expr && expr !== '') || !json) { 256 | return undefined; 257 | } 258 | 259 | const exprList = JSONPath.toPathArray(expr); 260 | if (exprList[0] === '$' && exprList.length > 1) { 261 | exprList.shift(); 262 | } 263 | this._hasParentSelector = null; 264 | const result = this 265 | ._trace( 266 | exprList, json, ['$'], currParent, currParentProperty, callback 267 | ) 268 | .filter(function (ea) { 269 | return ea && !ea.isParentSelector; 270 | }); 271 | 272 | if (!result.length) { 273 | return wrap ? [] : undefined; 274 | } 275 | if (!wrap && result.length === 1 && !result[0].hasArrExpr) { 276 | return this._getPreferredOutput(result[0]); 277 | } 278 | return result.reduce((rslt, ea) => { 279 | const valOrPath = this._getPreferredOutput(ea); 280 | if (flatten && Array.isArray(valOrPath)) { 281 | rslt = rslt.concat(valOrPath); 282 | } else { 283 | rslt.push(valOrPath); 284 | } 285 | return rslt; 286 | }, []); 287 | }; 288 | 289 | // PRIVATE METHODS 290 | 291 | JSONPath.prototype._getPreferredOutput = function (ea) { 292 | const resultType = this.currResultType; 293 | switch (resultType) { 294 | case 'all': { 295 | const path = Array.isArray(ea.path) 296 | ? ea.path 297 | : JSONPath.toPathArray(ea.path); 298 | ea.pointer = JSONPath.toPointer(path); 299 | ea.path = typeof ea.path === 'string' 300 | ? ea.path 301 | : JSONPath.toPathString(ea.path); 302 | return ea; 303 | } case 'value': case 'parent': case 'parentProperty': 304 | return ea[resultType]; 305 | case 'path': 306 | return JSONPath.toPathString(ea[resultType]); 307 | case 'pointer': 308 | return JSONPath.toPointer(ea.path); 309 | default: 310 | throw new TypeError('Unknown result type'); 311 | } 312 | }; 313 | 314 | JSONPath.prototype._handleCallback = function (fullRetObj, callback, type) { 315 | if (callback) { 316 | const preferredOutput = this._getPreferredOutput(fullRetObj); 317 | fullRetObj.path = typeof fullRetObj.path === 'string' 318 | ? fullRetObj.path 319 | : JSONPath.toPathString(fullRetObj.path); 320 | // eslint-disable-next-line n/callback-return -- No need to return 321 | callback(preferredOutput, type, fullRetObj); 322 | } 323 | }; 324 | 325 | /** 326 | * 327 | * @param {string} expr 328 | * @param {JSONObject} val 329 | * @param {string} path 330 | * @param {object|GenericArray} parent 331 | * @param {string} parentPropName 332 | * @param {JSONPathCallback} callback 333 | * @param {boolean} hasArrExpr 334 | * @param {boolean} literalPriority 335 | * @returns {ReturnObject|ReturnObject[]} 336 | */ 337 | JSONPath.prototype._trace = function ( 338 | expr, val, path, parent, parentPropName, callback, hasArrExpr, 339 | literalPriority 340 | ) { 341 | // No expr to follow? return path and value as the result of 342 | // this trace branch 343 | let retObj; 344 | if (!expr.length) { 345 | retObj = { 346 | path, 347 | value: val, 348 | parent, 349 | parentProperty: parentPropName, 350 | hasArrExpr 351 | }; 352 | this._handleCallback(retObj, callback, 'value'); 353 | return retObj; 354 | } 355 | 356 | const loc = expr[0], x = expr.slice(1); 357 | 358 | // We need to gather the return value of recursive trace calls in order to 359 | // do the parent sel computation. 360 | const ret = []; 361 | /** 362 | * 363 | * @param {ReturnObject|ReturnObject[]} elems 364 | * @returns {void} 365 | */ 366 | function addRet (elems) { 367 | if (Array.isArray(elems)) { 368 | // This was causing excessive stack size in Node (with or 369 | // without Babel) against our performance test: 370 | // `ret.push(...elems);` 371 | elems.forEach((t) => { 372 | ret.push(t); 373 | }); 374 | } else { 375 | ret.push(elems); 376 | } 377 | } 378 | if ((typeof loc !== 'string' || literalPriority) && val && 379 | Object.hasOwn(val, loc) 380 | ) { // simple case--directly follow property 381 | addRet(this._trace(x, val[loc], push(path, loc), val, loc, callback, 382 | hasArrExpr)); 383 | // eslint-disable-next-line unicorn/prefer-switch -- Part of larger `if` 384 | } else if (loc === '*') { // all child properties 385 | this._walk(val, (m) => { 386 | addRet(this._trace( 387 | x, val[m], push(path, m), val, m, callback, true, true 388 | )); 389 | }); 390 | } else if (loc === '..') { // all descendent parent properties 391 | // Check remaining expression with val's immediate children 392 | addRet( 393 | this._trace(x, val, path, parent, parentPropName, callback, 394 | hasArrExpr) 395 | ); 396 | this._walk(val, (m) => { 397 | // We don't join m and x here because we only want parents, 398 | // not scalar values 399 | if (typeof val[m] === 'object') { 400 | // Keep going with recursive descent on val's 401 | // object children 402 | addRet(this._trace( 403 | expr.slice(), val[m], push(path, m), val, m, callback, true 404 | )); 405 | } 406 | }); 407 | // The parent sel computation is handled in the frame above using the 408 | // ancestor object of val 409 | } else if (loc === '^') { 410 | // This is not a final endpoint, so we do not invoke the callback here 411 | this._hasParentSelector = true; 412 | return { 413 | path: path.slice(0, -1), 414 | expr: x, 415 | isParentSelector: true 416 | }; 417 | } else if (loc === '~') { // property name 418 | retObj = { 419 | path: push(path, loc), 420 | value: parentPropName, 421 | parent, 422 | parentProperty: null 423 | }; 424 | this._handleCallback(retObj, callback, 'property'); 425 | return retObj; 426 | } else if (loc === '$') { // root only 427 | addRet(this._trace(x, val, path, null, null, callback, hasArrExpr)); 428 | } else if ((/^(-?\d*):(-?\d*):?(\d*)$/u).test(loc)) { // [start:end:step] Python slice syntax 429 | addRet( 430 | this._slice(loc, x, val, path, parent, parentPropName, callback) 431 | ); 432 | } else if (loc.indexOf('?(') === 0) { // [?(expr)] (filtering) 433 | if (this.currEval === false) { 434 | throw new Error('Eval [?(expr)] prevented in JSONPath expression.'); 435 | } 436 | const safeLoc = loc.replace(/^\?\((.*?)\)$/u, '$1'); 437 | // check for a nested filter expression 438 | const nested = (/@.?([^?]*)[['](\??\(.*?\))(?!.\)\])[\]']/gu).exec(safeLoc); 439 | if (nested) { 440 | // find if there are matches in the nested expression 441 | // add them to the result set if there is at least one match 442 | this._walk(val, (m) => { 443 | const npath = [nested[2]]; 444 | const nvalue = nested[1] 445 | ? val[m][nested[1]] 446 | : val[m]; 447 | const filterResults = this._trace(npath, nvalue, path, 448 | parent, parentPropName, callback, true); 449 | if (filterResults.length > 0) { 450 | addRet(this._trace(x, val[m], push(path, m), val, 451 | m, callback, true)); 452 | } 453 | }); 454 | } else { 455 | this._walk(val, (m) => { 456 | if (this._eval(safeLoc, val[m], m, path, parent, 457 | parentPropName)) { 458 | addRet(this._trace(x, val[m], push(path, m), val, m, 459 | callback, true)); 460 | } 461 | }); 462 | } 463 | } else if (loc[0] === '(') { // [(expr)] (dynamic property/index) 464 | if (this.currEval === false) { 465 | throw new Error('Eval [(expr)] prevented in JSONPath expression.'); 466 | } 467 | // As this will resolve to a property name (but we don't know it 468 | // yet), property and parent information is relative to the 469 | // parent of the property to which this expression will resolve 470 | addRet(this._trace(unshift( 471 | this._eval( 472 | loc, val, path.at(-1), 473 | path.slice(0, -1), parent, parentPropName 474 | ), 475 | x 476 | ), val, path, parent, parentPropName, callback, hasArrExpr)); 477 | } else if (loc[0] === '@') { // value type: @boolean(), etc. 478 | let addType = false; 479 | const valueType = loc.slice(1, -2); 480 | switch (valueType) { 481 | case 'scalar': 482 | if (!val || !(['object', 'function'].includes(typeof val))) { 483 | addType = true; 484 | } 485 | break; 486 | case 'boolean': case 'string': case 'undefined': case 'function': 487 | if (typeof val === valueType) { 488 | addType = true; 489 | } 490 | break; 491 | case 'integer': 492 | if (Number.isFinite(val) && !(val % 1)) { 493 | addType = true; 494 | } 495 | break; 496 | case 'number': 497 | if (Number.isFinite(val)) { 498 | addType = true; 499 | } 500 | break; 501 | case 'nonFinite': 502 | if (typeof val === 'number' && !Number.isFinite(val)) { 503 | addType = true; 504 | } 505 | break; 506 | case 'object': 507 | if (val && typeof val === valueType) { 508 | addType = true; 509 | } 510 | break; 511 | case 'array': 512 | if (Array.isArray(val)) { 513 | addType = true; 514 | } 515 | break; 516 | case 'other': 517 | addType = this.currOtherTypeCallback( 518 | val, path, parent, parentPropName 519 | ); 520 | break; 521 | case 'null': 522 | if (val === null) { 523 | addType = true; 524 | } 525 | break; 526 | /* c8 ignore next 2 */ 527 | default: 528 | throw new TypeError('Unknown value type ' + valueType); 529 | } 530 | if (addType) { 531 | retObj = {path, value: val, parent, parentProperty: parentPropName}; 532 | this._handleCallback(retObj, callback, 'value'); 533 | return retObj; 534 | } 535 | // `-escaped property 536 | } else if (loc[0] === '`' && val && Object.hasOwn(val, loc.slice(1))) { 537 | const locProp = loc.slice(1); 538 | addRet(this._trace( 539 | x, val[locProp], push(path, locProp), val, locProp, callback, 540 | hasArrExpr, true 541 | )); 542 | } else if (loc.includes(',')) { // [name1,name2,...] 543 | const parts = loc.split(','); 544 | for (const part of parts) { 545 | addRet(this._trace( 546 | unshift(part, x), val, path, parent, parentPropName, callback, 547 | true 548 | )); 549 | } 550 | // simple case--directly follow property 551 | } else if ( 552 | !literalPriority && val && Object.hasOwn(val, loc) 553 | ) { 554 | addRet( 555 | this._trace(x, val[loc], push(path, loc), val, loc, callback, 556 | hasArrExpr, true) 557 | ); 558 | } 559 | 560 | // We check the resulting values for parent selections. For parent 561 | // selections we discard the value object and continue the trace with the 562 | // current val object 563 | if (this._hasParentSelector) { 564 | for (let t = 0; t < ret.length; t++) { 565 | const rett = ret[t]; 566 | if (rett && rett.isParentSelector) { 567 | const tmp = this._trace( 568 | rett.expr, val, rett.path, parent, parentPropName, callback, 569 | hasArrExpr 570 | ); 571 | if (Array.isArray(tmp)) { 572 | ret[t] = tmp[0]; 573 | const tl = tmp.length; 574 | for (let tt = 1; tt < tl; tt++) { 575 | // eslint-disable-next-line @stylistic/max-len -- Long 576 | // eslint-disable-next-line sonarjs/updated-loop-counter -- Convenient 577 | t++; 578 | ret.splice(t, 0, tmp[tt]); 579 | } 580 | } else { 581 | ret[t] = tmp; 582 | } 583 | } 584 | } 585 | } 586 | return ret; 587 | }; 588 | 589 | JSONPath.prototype._walk = function (val, f) { 590 | if (Array.isArray(val)) { 591 | const n = val.length; 592 | for (let i = 0; i < n; i++) { 593 | f(i); 594 | } 595 | } else if (val && typeof val === 'object') { 596 | Object.keys(val).forEach((m) => { 597 | f(m); 598 | }); 599 | } 600 | }; 601 | 602 | JSONPath.prototype._slice = function ( 603 | loc, expr, val, path, parent, parentPropName, callback 604 | ) { 605 | if (!Array.isArray(val)) { 606 | return undefined; 607 | } 608 | const len = val.length, parts = loc.split(':'), 609 | step = (parts[2] && Number.parseInt(parts[2])) || 1; 610 | let start = (parts[0] && Number.parseInt(parts[0])) || 0, 611 | end = (parts[1] && Number.parseInt(parts[1])) || len; 612 | start = (start < 0) ? Math.max(0, start + len) : Math.min(len, start); 613 | end = (end < 0) ? Math.max(0, end + len) : Math.min(len, end); 614 | const ret = []; 615 | for (let i = start; i < end; i += step) { 616 | const tmp = this._trace( 617 | unshift(i, expr), val, path, parent, parentPropName, callback, true 618 | ); 619 | // Should only be possible to be an array here since first part of 620 | // ``unshift(i, expr)` passed in above would not be empty, nor `~`, 621 | // nor begin with `@` (as could return objects) 622 | // This was causing excessive stack size in Node (with or 623 | // without Babel) against our performance test: `ret.push(...tmp);` 624 | tmp.forEach((t) => { 625 | ret.push(t); 626 | }); 627 | } 628 | return ret; 629 | }; 630 | 631 | JSONPath.prototype._eval = function ( 632 | code, _v, _vname, path, parent, parentPropName 633 | ) { 634 | this.currSandbox._$_parentProperty = parentPropName; 635 | this.currSandbox._$_parent = parent; 636 | this.currSandbox._$_property = _vname; 637 | this.currSandbox._$_root = this.json; 638 | this.currSandbox._$_v = _v; 639 | 640 | const containsPath = code.includes('@path'); 641 | if (containsPath) { 642 | this.currSandbox._$_path = JSONPath.toPathString(path.concat([_vname])); 643 | } 644 | 645 | const scriptCacheKey = this.currEval + 'Script:' + code; 646 | if (!JSONPath.cache[scriptCacheKey]) { 647 | let script = code 648 | .replaceAll('@parentProperty', '_$_parentProperty') 649 | .replaceAll('@parent', '_$_parent') 650 | .replaceAll('@property', '_$_property') 651 | .replaceAll('@root', '_$_root') 652 | .replaceAll(/@([.\s)[])/gu, '_$_v$1'); 653 | if (containsPath) { 654 | script = script.replaceAll('@path', '_$_path'); 655 | } 656 | if ( 657 | this.currEval === 'safe' || 658 | this.currEval === true || 659 | this.currEval === undefined 660 | ) { 661 | JSONPath.cache[scriptCacheKey] = new this.safeVm.Script(script); 662 | } else if (this.currEval === 'native') { 663 | JSONPath.cache[scriptCacheKey] = new this.vm.Script(script); 664 | } else if ( 665 | typeof this.currEval === 'function' && 666 | this.currEval.prototype && 667 | Object.hasOwn(this.currEval.prototype, 'runInNewContext') 668 | ) { 669 | const CurrEval = this.currEval; 670 | JSONPath.cache[scriptCacheKey] = new CurrEval(script); 671 | } else if (typeof this.currEval === 'function') { 672 | JSONPath.cache[scriptCacheKey] = { 673 | runInNewContext: (context) => this.currEval(script, context) 674 | }; 675 | } else { 676 | throw new TypeError(`Unknown "eval" property "${this.currEval}"`); 677 | } 678 | } 679 | 680 | try { 681 | return JSONPath.cache[scriptCacheKey].runInNewContext(this.currSandbox); 682 | } catch (e) { 683 | if (this.ignoreEvalErrors) { 684 | return false; 685 | } 686 | throw new Error('jsonPath: ' + e.message + ': ' + code); 687 | } 688 | }; 689 | 690 | // PUBLIC CLASS PROPERTIES AND METHODS 691 | 692 | // Could store the cache object itself 693 | JSONPath.cache = {}; 694 | 695 | /** 696 | * @param {string[]} pathArr Array to convert 697 | * @returns {string} The path string 698 | */ 699 | JSONPath.toPathString = function (pathArr) { 700 | const x = pathArr, n = x.length; 701 | let p = '$'; 702 | for (let i = 1; i < n; i++) { 703 | if (!(/^(~|\^|@.*?\(\))$/u).test(x[i])) { 704 | p += (/^[0-9*]+$/u).test(x[i]) ? ('[' + x[i] + ']') : ("['" + x[i] + "']"); 705 | } 706 | } 707 | return p; 708 | }; 709 | 710 | /** 711 | * @param {string} pointer JSON Path 712 | * @returns {string} JSON Pointer 713 | */ 714 | JSONPath.toPointer = function (pointer) { 715 | const x = pointer, n = x.length; 716 | let p = ''; 717 | for (let i = 1; i < n; i++) { 718 | if (!(/^(~|\^|@.*?\(\))$/u).test(x[i])) { 719 | p += '/' + x[i].toString() 720 | .replaceAll('~', '~0') 721 | .replaceAll('/', '~1'); 722 | } 723 | } 724 | return p; 725 | }; 726 | 727 | /** 728 | * @param {string} expr Expression to convert 729 | * @returns {string[]} 730 | */ 731 | JSONPath.toPathArray = function (expr) { 732 | const {cache} = JSONPath; 733 | if (cache[expr]) { 734 | return cache[expr].concat(); 735 | } 736 | const subx = []; 737 | const normalized = expr 738 | // Properties 739 | .replaceAll( 740 | /@(?:null|boolean|number|string|integer|undefined|nonFinite|scalar|array|object|function|other)\(\)/gu, 741 | ';$&;' 742 | ) 743 | // Parenthetical evaluations (filtering and otherwise), directly 744 | // within brackets or single quotes 745 | .replaceAll(/[['](\??\(.*?\))[\]'](?!.\])/gu, function ($0, $1) { 746 | return '[#' + (subx.push($1) - 1) + ']'; 747 | }) 748 | // Escape periods and tildes within properties 749 | .replaceAll(/\[['"]([^'\]]*)['"]\]/gu, function ($0, prop) { 750 | return "['" + prop 751 | .replaceAll('.', '%@%') 752 | .replaceAll('~', '%%@@%%') + 753 | "']"; 754 | }) 755 | // Properties operator 756 | .replaceAll('~', ';~;') 757 | // Split by property boundaries 758 | .replaceAll(/['"]?\.['"]?(?![^[]*\])|\[['"]?/gu, ';') 759 | // Reinsert periods within properties 760 | .replaceAll('%@%', '.') 761 | // Reinsert tildes within properties 762 | .replaceAll('%%@@%%', '~') 763 | // Parent 764 | .replaceAll(/(?:;)?(\^+)(?:;)?/gu, function ($0, ups) { 765 | return ';' + ups.split('').join(';') + ';'; 766 | }) 767 | // Descendents 768 | .replaceAll(/;;;|;;/gu, ';..;') 769 | // Remove trailing 770 | .replaceAll(/;$|'?\]|'$/gu, ''); 771 | 772 | const exprList = normalized.split(';').map(function (exp) { 773 | const match = exp.match(/#(\d+)/u); 774 | return !match || !match[1] ? exp : subx[match[1]]; 775 | }); 776 | cache[expr] = exprList; 777 | return cache[expr].concat(); 778 | }; 779 | 780 | JSONPath.prototype.safeVm = { 781 | Script: SafeScript 782 | }; 783 | 784 | export {JSONPath}; 785 | --------------------------------------------------------------------------------