yoursunny/nfdc-design.md

## nfdc-design.md

      
    Raw
  

              nfdc-design.md
            
          
    nfdc interactive design

This document proposes a new design for nfdc command which combines existing nfdc and nfd-status commands, as a unified command for monitoring and controlling NFD.
operation modes

nfdc has three operation modes.
one-shot mode executes a single command. An example interaction looks like:
$ nfdc face
id=288 local=udp4://192.0.2.1:6363 remote=udp4://192.0.2.8:6363 persistent in=500i,400d,20n,60000B out=450i,300d,100n,50000B
id=289 local=udp4://192.0.2.1:6363 remote=udp4://192.0.2.9:6363 persistent in=502i,402d,22n,60002B out=452i,302d,102n,50002B
$ nfdc face create udp4://router.example.com
face-created id=300 local=udp4://192.0.2.1:6363 remote=udp4://192.0.2.2:6363 persistent

batch mode executes multiple commands. nfdc -f <filename> executes a batch file. An example interaction looks like:
$ cat commands.txt
face create udp4://router.example.com permanent
route add / udp4://router.example.com cost 10
route add /corp udp4://router.example.org
$ nfdc -f command.txt
face-created id=300 local=udp4://192.0.2.1:6363 remote=udp4://192.0.2.2:6363 permanent
route-added prefix=/ nexthop=300 cost=10 origin=255
face-created id=301 local=udp4://192.0.2.1:6363 remote=udp4://192.0.2.3:6363 persistent
route-added prefix=/corp nexthop=301 cost=0 origin=255
$ echo $?
0

interactive mode displays a command prompt and allows the operator to type in commands. nfdc -i enters the interactive mode. An example interaction looks like:
$ nfdc -i
nfdc> face
nfdc face> list
id=288 local=udp4://192.0.2.1:6363 remote=udp4://192.0.2.8:6363 persistent in=500i,400d,20n,60000B out=450i,300d,100n,50000B
id=289 local=udp4://192.0.2.1:6363 remote=udp4://192.0.2.9:6363 persistent in=502i,402d,22n,60002B out=452i,302d,102n,50002B
nfdc face> create udp4://router.example.com permanent
face-created id=300 local=udp4://192.0.2.1:6363 remote=udp4://192.0.2.2:6363 permanent
nfdc face> exit
nfdc> route add / udp4://router.example.com cost 10
route-added prefix=/ nexthop=300 cost=10 origin=255
nfdc> quit

input and output format

command line

nfdc accepts inputs in the form of command line. In one-shot mode, each invocation accepts a command line; in batch mode, each line in the batch file is a command line.
A command line starts with a noun and a verb, followed by zero or more arguments.
The noun denotes an item that can be operated on. It should be written in singular form. Examples are: status, face, strategy, route.
The verb denotes an action to be carried on the item. It should be written in present tense. Examples are: list, show, create, destroy, add, remove, set, unset, load, unload, reset.
A combination of module and verb defines a command.
All arguments are named. Each named argument should be specified as the name followed by the value; the value can have zero or more tokens.
In addition, each command may accept zero or more commonly used arguments as positional arguments; in other words, the argument name can be omitted if they are specified in the defined order. For an argument to be accepted as a positional argument, its value must be distinguishable from possible argument names. Positional arguments must be specified before any named arguments.
face create command accepts remote and persistency as two positional arguments, so the following command lines are equivalent:
face create udp4://router.example.com persistent
face create udp4://router.example.com persistency persistent
face create remote udp4://router.example.com persistency persistent
face create persistency persistent remote udp4://router.example.com

In one-shot and batch modes, if a command line has only the module, verb list is implied.
The following command lines are equivalent in one-shot and batch modes:
face
face list

command result

A command line, except those requesting information, yields one or more command results.
A positive result indicates a successful command execution.
It starts with an action summary which contains the noun, a hyphen, and the verb as past particle. Examples are: face-created, strategy-set, route-added. The action summary is written as one token for easier script consumption; it's also human readable.
After the action summary, attributes of the item is printed as key-value pairs separated by spaces; each key-value pair is represented as key=value. If the key corresponds to a command argument, it should use the same word as the argument name.
A negative result indicates a failed command execution.
It starts with a failure summary which is similar to the action summary but with the word "not" injected in between. Examples are: face-not-created, strategy-not-set, route-not-added.
Then it's a reason summary which indicates the failure reason. Examples are: timeout, not-authorized, bad-response, response-validation-error. The reason summary is written as one token for easier script consumption; it's also human readable.
After the failure summary and reason summary, key-value pairs about the failure can be printed in the same format as a positive result.
status report

A command line requesting information, typically with list or show verb, yields a status report.
A status report of one item (typically from show verb) should print one attribute per line.
A status report of multiple items (typically from list verb) should print one item per line, and use tab-separated or key=value format on each line.
list of commands

This section gives a brief list of all commands and their arguments.
status show # general status

status list # alias of "status show"

status report [[format] text] # full status report in text

status report [format] xml # full status report in XML

face list [[remote] <uri>] [local <uri>] [scheme <scheme>]

face show [id] <id>

face create [remote] <uri> [[persistency] <persistent|permanent>]

face destroy [id] <id>

face destroy [remote] <uri>

channel list

strategy list

strategy show [prefix] <prefix>

strategy set [prefix] <prefix> [strategy] <strategy-name>

strategy unset [prefix] <prefix>

fib list

route list [[nexthop] <id|uri>] [origin <origin>]

route show [prefix] <prefix>

route add [prefix] <prefix> [nexthop] <id|uri> [cost <cost>] [origin <origin>] [no-inherit] [capture] [expires <millis>]

route remove [prefix] <prefix> [nexthop] <id|uri> [origin <origin>]

getting help

In one-shot and interactive modes, a help command is provided. This command has a special syntax that it does not have a noun before help verb, and its arguments are positional only.
help [<noun> [<verb>]]

In one-shot mode:

help prints a list of commands each with a brief single-line description.
help <noun> prints a list of verbs under the noun each with a brief description, which may contain commonly used arguments.
help <noun> <verb> prints detailed help.

In interactive mode when the current noun is empty:

help prints a list of nouns each with a brief single-line description, plus help, exit, and quit.
help <noun> and help <noun> <verb> behave same as in one-shot mode.

In interactive mode when the current noun is not empty:

help prints a list of verbs under the current noun, and a list of nouns, each with a brief single-line description, plus help, exit, and quit.
help <noun> and help <noun> <verb> behave same as in one-shot mode.
help <verb> where the verb is valid under the current noun behaves same as help <current-noun> <verb>.

help command is not supported in batch mode.
nfdc -h or nfdc (without arguments) prints an introduction on the three operating modes, and an invitation on getting more help with nfdc help.
interactive mode

Under interactive mode, the program remembers a current noun; initially, the current noun is empty.
The prompt should start with nfdc, followed by the current noun if not empty, and then a > symbol.
Each typed line can be one of:

A noun. This changes the current noun to this noun.
A complete command line starting with noun and verb. This executes the command without considering or changing the current noun.
A command line without the noun, when the current noun is not empty. This executes the command as if the current noun is specified on the command line.
quit. This stops the program.
exit. If the current noun is empty, this is equivalent to quit; otherwise, this clears the current noun to empty.

instant help

In interactive mode, pressing TAB or ? key shows possible completions of the current token, or possible next tokens if the current token is complete.
legacy support

Old nfdc and nfd-status commands are mapped into new commands as:
nfdc register => route add
nfdc unregister => route remove
nfdc create => face create
nfdc destroy => face destroy
nfdc set-strategy => strategy set
nfdc unset-strategy => strategy unset
nfdc add-nexthop => (not supported)
nfdc remove-nexthop => (not supported)
nfd-status => status report text
nfd-status -x => status report xml
nfd-status --general => status show
nfd-status --channels => channel list
nfd-status --faces => face list
nfd-status --fib => fib-entry list
nfd-status --rib => route list
nfd-status --sc => strategy list

implementation plan

This design can be implemented in stages.
The initial steps are:

Merge nfdc and nfd-status, support only one-shot mode, keep old output format.

Move classes in nfd::tools::nfd_status namespace to nfd::tools::nfdc namespace.
Rename nfdc::Nfdc class to nfd::tools::nfdc::LegacyNfdc.
Implement a nfd-status shell script which invokes nfdc legacy-nfd-status "$@".
Implement command line parsing logic that supports new syntax, old nfdc syntax, and legacy-nfd-status hidden command for old nfd-status syntax. The command line parsing logic should be implemented in a class rather than in the main function, so that it can be reused in batch/interactive modes; a parameter should be provided to disallow old syntax because old syntax is only allowed in one-shot mode.
Dispatch commands to either StatusReport or LegacyNfdc class.
Output format remains same as old nfdc and nfd-status.
help command is not supported, but -h displays a help message either hard-coded or produced by command line parser.


Change output format, one module at a time.

Implement command execution logic of the module into a Module subclass, and delete the equivalent function from LegacyNfdc class.
Make command execution output in the format defined in this design.
Dispatch command to Module subclass instead of LegacyNfdc.


Implement help command.
Implement batch mode.