yang-forge

YANG package manager and runtime engine

yfc is the command utility providing YANG model-driven application lifecycle management.

It provides advanced abstractions on top of yang-cc for richer schema interactions and flexible runtime capabilities such as dynamic interface generation (cli, express, restjson, websockets).

This module is a special core generated using the yang-cc application core composition library based on yang-forge-core.yang schema.

This software is brought to you by Corenova. We'd love to hear your feedback. Please feel free to reach me at [email protected] anytime with questions, suggestions, etc.

It is written primarily using CoffeeScript and runs on Node.js and the web browser.

Installation

$ npm install -g yang-forge

You must have node >= 0.10.28 as a minimum requirement to run yang-forge.

Usage

  Usage: yfc [options] [command]


  Commands:

    schema [options] [file]     process a specific YANG schema file or string
    build [options] [file...]   package the module(s) for deployment/publishing
    inspect [options] [core]    inspect a given core package file to extract metadata
    run [options] [module...]   runs one or more core(s) and module(s)
    deploy                      deploy core(s) into target endpoint (planned)
    info [options] [core]       shows info about a published core from the registry (planned)
    search [keyword...]         search the registry for cores matching keywords (planned)
    publish [options]           publish package to upstream registry (planned)
    translate [options] [file]  translates input configuration data according to available YANG schema(s) (planned)

  This module provides YANG package management and runtime engine operations

  Options:

    -h, --help     output usage information
    -V, --version  output the version number
    -v, --verbose  increase verbosity
    --no-color     disable color output

The yfc command-line interface is runtime-generated according to yang-forge-core.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 dynamically linked by the yang-cc composer by inspecting the lib directory in the package.

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 yang_debug=1 to get complete debug output of the execution log.

$ yang_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.

Available 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.

API

Here's an example for using this module:

yf = require 'yang-forge'
yf.run 'express', 5050 # fire up express instance on port 5050
yf.run 'restjson'      # bind restjson interface generator to express
yf.run 'websocket'     # bind socket.io to express

Since YangForge itself is a YANG schema (yang-forge-core.yang) compiled module, it is simply the Core object instance generated by the yang-cc module.

You can also interact with the yang-forge-core module instance directly to invoke the various RPC methods available.

yf = require 'yang-forge'
forge = yf.access 'yang-forge-core' # grab the yang-forge-core module
forge.invoke 'build', arguments: [ 'foo.yang', 'bar.yang' ]
.then (res) ->
  console.log res.get()

The above example will generate a new composition output similarly to what yang-cc produced. For more info on other RPC methods available, take a look at the yang-forge-core.yang schema.

Major changes from prior 0.11.x branch

Please note that the newly designed YangForge no longer contains native interfaces to compiler methods such as parse/load/compile/etc. In order to access previous capabilities, you can consider utilizing the rpc schema interface via the invoke mechanism or just use the underlying yang-js or yang-cc modules directly.

This design change is a result of modularizing the earlier YangForge project into three distinct components:

name | description --- | --- yang-js | YANG parser and compiler yang-cc | YANG model-driven application core composer yang-forge | YANG package manager and runtime engine

Furthermore, previous YAML schema to represent a forged module (with dependencies and behaviors) for a target YANG schema has been superceded by the new composition and specification custom YANG extensions.

Due to potential breaking changes and other considerations, the previous yangforge package has been renamed to yang-forge and the former package will be marked deprecated but preserved for the near future.

License

Apache 2.0