yfc -- YangForge Controller
yfc
is the command shell for the YangForge framework, providing
schema-driven application lifecycle management.
YangForge
provides runtime JavaScript execution based on YANG schema
modeling language as defined in IETF drafts and standards
(RFC 6020).
Basically, the framework enables YANG schema language to become a programming language.
It also utilizes YAML with custom tags to construct a portable module with embedded code.
It is written primarily using CoffeeScript and runs on Node.js and the web browser (yes, it's isomorphic).
This software is sponsored by
ClearPath Networks on behalf of the
OPNFV (Open Platform for Network Functions
Virtualization) community. For a reference implementation created entirely utilizing YangForge
, please take a look at OPNFV Promise which provides future resource/capacity management (reservations/allocations) for virtualized infrastructure.
Please note that this project is under active development. Be sure to check back often as new updates are being pushed regularly.
Installation
$ npm install -g yangforge
You must have node >= 0.10.28
as a minimum requirement to run
yangforge
.
Usage
Usage: yfc [options] [command]
Commands:
build [options] [file] package the application for deployment
config manage yangforge service configuration (planned)
deploy deploy application into yangforge endpoint (planned)
info [options] [name] shows info about a specific module
publish [options] publish package to upstream registry (planned)
run [options] [modules...] runs one or more modules and/or schemas
schema [options] [file] process a specific YANG schema file or string
sign sign package to ensure authenticity (planned)
YANG driven JS application builder
Options:
-h, --help output usage information
-V, --version output the version number
--no-color disable color output
The yfc
command-line interface is runtime-generated according to
yangforge.yang schema definitions. Please refer to
the schema section covering various rpc
extension statements and
sub-statement definitions for a reference regarding different types of
command-line arguments, descriptions, and options processing syntax.
The corresponding actions for each of the rpc
extensions are
implemented inside the YangForge
YAML module
package.yaml.
For comprehensive usage documentation around various CLI commands, please refer to the YangForge Examples README.
Troubleshooting
When you encounter errors or issues while utilizing the yfc
command
line utility, you can set ENVIRONMENTAL variable yfc_debug=1
to get
complete debug output of the YangForge
execution log.
$ yfc_debug=1 yfc <some-command>
The output generated is very verbose and may or may not assist you in determining the root cause. However, when reporting an issue into the Github repository, it will be helpful to paste a snippet of the debug output for quicker resolution by the project maintainer.
Bundled YANG schema modules
There are a number of YANG schema modules commonly referenced and
utilized by other YANG modules during schema definition and they have
been bundled together into the yangforge
package for convenience.
All you need to do is to import <module name>
from your YANG schema
and they will be retrieved/resolved automatically.
name | description | reference |
---|---|---|
complex-types | extensions to model complex types and typed instance identifiers | RFC-6095 |
iana-crypt-hash | typedef for storing passwords using a hash function | RFC-7317 |
ietf-inet-types | collection of generally useful types for Internet addresses | RFC-6991 |
ietf-yang-types | collection of generally useful derived data types | RFC-6991 |
Additional YANG modules will be bundled into the yangforge
package
over time. Since yangforge
facilitate forging of new YANG modules
and easily using them in your own projects, only industry standards
based YANG schema modules will be considered for native bundling at
this time.
Bundled YANG features
name | description | dependency |
---|---|---|
cli | generates command-line interface | none |
express | generates HTTP/HTTPS web server instance | none |
restjson | generates REST/JSON web services interface | express |
websocket | generates socket.io interface | express |
You can click on the name entry above for reference documentation on each feature module.
Using YangForge Programmatically
forge = require 'yangforge'forgeimport 'my-cool-schema.yang'then consolelog appinfo
Key Features
- Parse YAML/YANG/JSON schema files and generate runtime JavaScript semantic object tree hierarchy
- Import/Export capabilities to load modules using customizable importers based on regular expressions and custom import routines. Ability to serialize module meta data into JSON format that is portable across systems. Also exports serialized JS functions as part of export meta data.
- Runtime Generation allows compiler to directly create a live JS
class object definition so that it can be instantiated via
new
keyword and used immediately - Dynamic Extensions enable compiler to be configured with
alternative
resolver
functions to change the behavior of produced output
YangForge itself is also a YANG schema (yangforge.yang) compiled module. It is compiled by the yang-compiler and natively includes yang-v1-extensions submodule for supporting the YANG version 1.0 (RFC 6020) specifications. Please reference the yang-v1-extensions documentation for up-to-date info on YANG 1.0 language coverage status. It serves as a good reference for writing new compilers, custom extensions, custom typedefs, among other things.
Primary interfaces
name | description |
---|---|
forge.import | local/remote async loading of one or more modules using filenames |
forge.load | local async/sync loading of module(s), only one-at-a-time with sync |
forge.compile | local sync compilation of a module, generates class obj that can be instantiated |
forge.preprocess | local sync preprocessing of a module, constraint validations, schema manipulations |
forge.parse | local sync parsing of a module, syntax validations, custom-tag resolutions |
Programmatic Usage Examples
The below examples can be executed using CoffeeScript REPL by running
coffee
at the command-line from the top-directory of this repo.
Using the native YangForge module as a library:
forge = require 'yangforge' yang = """ module hello-world { description "a test"; leaf hello { type string; default "world"; } } """ # asynchronous load YANG schema forgeload schema: yangthen consolelog appget 'hello-world.hello' appset 'hello-world.hello''goodbye' consolelog appget # synchronous load YANG schema app = forgeload schmea: yangasync: falseconsolelog appinfo format: 'json' # compile YANG schema model as class object HelloWorld = forgecompile schema: yanghello = 'hello-world': hello: 'howdy there'consolelog helloget yaml = """ name: hello schema: !yang | module embedded-world { leaf wow { type number; default 0; } } config: !json | { "embedded-world": { "wow": 2 } } """ # it can do YAML quite well forgeload yamlthen consolelog appget # sometimes you just want to preprocess to see what it becomes consolelog forgepreprocess yaml
Forging a new module/application for build/publish using YAML (see also complex-types):
name: some-new-applicationschema: !yang some-new-applicationyangrpc: something-useful: !coffee/function consolelog inputget outputset 'important data' done
Forging a new interface generator using YAML (see also cli example):
name: some-new-interfacedescription: Some new awesome interfacerun: !coffee/function (model, options) -> # code logic to dynamically construct a new interface based on passed-in context console.log model
There are many other ways of interacting with the module's class object as well as the instantiated class.
More examples coming soon!
Literate CoffeeScript Documentation
The source code is documented in Markdown format. It's code combined with documentation all-in-one.
- YangForge
- External Dependencies