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'
forge.import 'my-cool-schema.yang'
.then (app) ->
  console.log app.info()

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
forge.load schema: yang
.then (app) ->
  console.log app.get 'hello-world.hello'
  app.set 'hello-world.hello', 'goodbye'
  console.log app.get()

# synchronous load YANG schema
app = forge.load schmea: yang, async: false
console.log app.info format: 'json'

# compile YANG schema model as class object
HelloWorld = forge.compile schema: yang
hello = new HelloWorld 'hello-world': hello: 'howdy there'
console.log hello.get()

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
forge.load yaml
.then (app) ->
  console.log app.get()

# sometimes you just want to preprocess to see what it becomes
console.log forge.preprocess yaml

Forging a new module/application for build/publish using YAML (see also complex-types):

name: some-new-application
schema: !yang some-new-application.yang
rpc:
  something-useful: !coffee/function
    (input, output, done) ->
      console.log input.get()
      output.set 'important data'
      done()

Forging a new interface generator using YAML (see also cli example):

name: some-new-interface
description: Some new awesome interface
run: !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
  • Compiler
  • Features
  • Module
  • Schema
• External Dependencies
  • data-synth library
  • js-yaml library
  • yang-parser library

License

Apache 2.0