src/main/java/com/intel/jndn/management/Nfdc.java

/*
 * jndn-management
 * Copyright (c) 2015-2018, Intel Corporation.
 *
 * This program is free software; you can redistribute it and/or modify it
 * under the terms and conditions of the GNU Lesser General Public License,
 * version 3, as published by the Free Software Foundation.
 *
 * This program is distributed in the hope it will be useful, but WITHOUT ANY
 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
 * more details.
 */
package com.intel.jndn.management;

import com.intel.jndn.management.enums.RouteOrigin;
import com.intel.jndn.management.helpers.FetchHelper;
import com.intel.jndn.management.helpers.StatusDatasetHelper;
import com.intel.jndn.management.types.ChannelStatus;
import com.intel.jndn.management.types.FaceStatus;
import com.intel.jndn.management.types.FibEntry;
import com.intel.jndn.management.types.ForwarderStatus;
import com.intel.jndn.management.types.RibEntry;
import com.intel.jndn.management.types.StrategyChoice;
import net.named_data.jndn.ControlParameters;
import net.named_data.jndn.ControlResponse;
import net.named_data.jndn.Data;
import net.named_data.jndn.Face;
import net.named_data.jndn.Interest;
import net.named_data.jndn.KeyLocator;
import net.named_data.jndn.Name;
import net.named_data.jndn.RegistrationOptions;
import net.named_data.jndn.encoding.EncodingException;
import net.named_data.jndn.security.SecurityException;

import java.io.IOException;
import java.util.List;

/**
 * Helper class for interacting with an NDN forwarder daemon; see
 * <a href="https://redmine.named-data.net/projects/nfd/wiki/Management">NFD Management</a>
 * for explanations of the various protocols used.
 *
 * @author Andrew Brown <andrew.brown@intel.com>
 */
public final class Nfdc {
  private static final int OK_STATUS = 200;
  private static final int FACE_ALREADY_EXISTS = 409;

  /////////////////////////////////////////////////////////////////////////////

  /**
   * Prevent creation of Nfdc instances.
   */
  private Nfdc() {
  }

  /**
   * Retrieve the status of the given forwarder; calls /localhost/nfd/status/general
   * which requires a local Face (all non-local packets are dropped).
   *
   * @param face only a localhost Face
   * @return the forwarder status object
   * @throws ManagementException if the network request failed or the returned status could not be decoded
   * @see <a href="https://redmine.named-data.net/projects/nfd/wiki/ForwarderStatus">ForwarderStatus</a>
   */
  public static ForwarderStatus getForwarderStatus(final Face face) throws ManagementException {
    try {
      List<Data> segments = FetchHelper.getSegmentedData(face, new Name("/localhost/nfd/status/general"));
      return new ForwarderStatus(StatusDatasetHelper.combine(segments));
    } catch (IOException | EncodingException e) {
      throw new ManagementException(e.getMessage(), e);
    }
  }

  /**
   * Retrieve a list of faces and their status from the given forwarder; calls
   * /localhost/nfd/faces/list which requires a local Face (all non-local
   * packets are dropped).
   *
   * @param face only a localhost Face
   * @return a list of face status objects
   * @throws ManagementException if the network request failed or if the NFD rejected the request
   * @see <a href="https://redmine.named-data.net/projects/nfd/wiki/FaceMgmt">FaceManagement</a>
   */
  public static List<FaceStatus> getFaceList(final Face face) throws ManagementException {
    try {
      List<Data> segments = FetchHelper.getSegmentedData(face, new Name("/localhost/nfd/faces/list"));
      return StatusDatasetHelper.wireDecode(segments, FaceStatus.class);
    } catch (IOException e) {
      throw new ManagementException(e.getMessage(), e);
    }
  }

  /**
   * Retrieve a list of FIB entries and their NextHopRecords from the given
   * forwarder; calls /localhost/nfd/fib/list which requires a local Face (all
   * non-local packets are dropped).
   *
   * @param face only a localhost Face
   * @return a list of FIB entries
   * @throws ManagementException if the network request failed or if the NFD rejected the request
   * @see <a href="https://redmine.named-data.net/projects/nfd/wiki/FibMgmt#FIB-Dataset">FIB Dataset</a>
   */
  public static List<FibEntry> getFibList(final Face face) throws ManagementException {
    try {
      List<Data> segments = FetchHelper.getSegmentedData(face, new Name("/localhost/nfd/fib/list"));
      return StatusDatasetHelper.wireDecode(segments, FibEntry.class);
    } catch (IOException e) {
      throw new ManagementException(e.getMessage(), e);
    }
  }

  /**
   * Retrieve a list of routing entries from the RIB; calls
   * /localhost/nfd/rib/list which requires a local Face (all non-local packets
   * are dropped).
   *
   * @param face only a localhost Face
   * @return a list of RIB entries, i.e. routes
   * @throws ManagementException if the network request failed or if the NFD rejected the request
   * @see <a href="https://redmine.named-data.net/projects/nfd/wiki/RibMgmt#RIB-Dataset">RIB Dataset</a>
   */
  public static List<RibEntry> getRouteList(final Face face) throws ManagementException {
    try {
      List<Data> segments = FetchHelper.getSegmentedData(face, new Name("/localhost/nfd/rib/list"));
      return StatusDatasetHelper.wireDecode(segments, RibEntry.class);
    } catch (IOException e) {
      throw new ManagementException(e.getMessage(), e);
    }
  }

  /**
   * Retrieve the list of strategy choice entries from the NFD; calls
   * /localhost/nfd/rib/list which requires a local Face (all non-local packets
   * are dropped).
   *
   * @param face only a localhost Face
   * @return a list of strategy choice entries, i.e. routes
   * @throws ManagementException if the network request failed, the NFD response could not be decoded, or
   *                             the NFD rejected the request
   * @see <a href="https://redmine.named-data.net/projects/nfd/wiki/StrategyChoice">StrategyChoice</a>
   */
  public static List<StrategyChoice> getStrategyList(final Face face) throws ManagementException {
    try {
      List<Data> segments = FetchHelper.getSegmentedData(face, new Name("/localhost/nfd/strategy-choice/list"));
      return StatusDatasetHelper.wireDecode(segments, StrategyChoice.class);
    } catch (IOException e) {
      throw new ManagementException(e.getMessage(), e);
    }
  }

  /**
   * Retrieve the list of channel status entries from the NFD; calls
   * /localhost/nfd/faces/channels which requires a local Face (all non-local packets
   * are dropped).
   *
   * @param face only a localhost Face
   * @return a list of channel status entries
   * @throws ManagementException if the network request failed, the NFD response could not be decoded, or
   *                             the NFD rejected the request
   * @see <a href="https://redmine.named-data.net/projects/nfd/wiki/FaceMgmt#Channel-Dataset">Face Management</a>
   */
  public static List<ChannelStatus> getChannelStatusList(final Face face) throws ManagementException {
    try {
      List<Data> segments = FetchHelper.getSegmentedData(face, new Name("/localhost/nfd/faces/channels"));
      return StatusDatasetHelper.wireDecode(segments, ChannelStatus.class);
    } catch (IOException e) {
      throw new ManagementException(e.getMessage(), e);
    }
  }

  /**
   * Retrieve the {@link KeyLocator} for an NFD.
   *
   * @param face only a localhost {@link Face}
   * @return the {@link KeyLocator} of the NFD's key
   * @throws ManagementException if the network request failed, if the NFD rejected the request, or no
   *                             KeyLocator was found
   */
  public static KeyLocator getKeyLocator(final Face face) throws ManagementException {
    try {
      List<Data> segments = FetchHelper.getSegmentedData(face, new Name("/localhost/nfd/status/general"));
      if (segments.isEmpty() || !KeyLocator.canGetFromSignature(segments.get(0).getSignature())) {
        throw new ManagementException("No key locator available.");
      }
      return KeyLocator.getFromSignature(segments.get(0).getSignature());
    } catch (IOException e) {
      throw new ManagementException(e.getMessage(), e);
    }
  }

  /**
   * Create a new face on the given forwarder. Ensure the forwarding face is on
   * the local machine (management requests are to /localhost/...) and that
   * command signing has been set up (e.g. forwarder.setCommandSigningInfo()).
   *
   * @param face only a localhost {@link Face}
   * @param uri  a string like "tcp4://host.name.com" (see nfd-status channels
   *             for more protocol options)
   * @return the newly created face ID
   * @throws ManagementException if the network request failed, the NFD response could not be decoded, or
   *                             the NFD rejected the request
   */
  public static int createFace(final Face face, final String uri) throws ManagementException {
    Name command = new Name("/localhost/nfd/faces/create");
    ControlParameters parameters = new ControlParameters();
    parameters.setUri(uri);
    command.append(parameters.wireEncode());

    try {
      // send the interest
      ControlResponse response = sendCommand(face, command);

      // return
      return response.getBodyAsControlParameters().getFaceId();
    } catch (IOException | EncodingException e) {
      throw new ManagementException(e.getMessage(), e);
    }
  }

  /**
   * Destroy a face on given forwarder. Ensure the forwarding face is on the
   * local machine (management requests are to /localhost/...) and that command
   * signing has been set up (e.g. forwarder.setCommandSigningInfo()).
   *
   * @param face   only a localhost {@link Face}
   * @param faceId the ID of the face to destroy
   * @throws ManagementException if the network request failed, the NFD response could not be decoded, or
   *                             the NFD rejected the request
   */
  public static void destroyFace(final Face face, final int faceId) throws ManagementException {
    Name command = new Name("/localhost/nfd/faces/destroy");
    ControlParameters parameters = new ControlParameters();
    parameters.setFaceId(faceId);
    command.append(parameters.wireEncode());

    try {
      sendCommand(face, command);
    } catch (IOException | EncodingException | ManagementException e) {
      throw new ManagementException(e.getMessage(), e);
    }
  }

  /**
   * Register a route on the forwarder.
   * <p/>
   * Ensure the forwarding face is on the local machine (management requests are to /localhost/...) and that command
   * signing has been set up (e.g. forwarder.setCommandSigningInfo()).
   *
   * @param face              only a localhost {@link Face}
   * @param controlParameters the {@link ControlParameters} command options
   * @throws ManagementException if the network request failed, the NFD response could not be decoded, or
   *                             the NFD rejected the request
   * @see <a href="http://named-data.net/doc/NFD/current/manpages/nfdc.html">nfdc</a>
   * @see <a href="https://redmine.named-data.net/projects/nfd/wiki/RibMgmt">RIB Management</a>
   */
  public static void register(final Face face, final ControlParameters controlParameters) throws ManagementException {
    // build command name
    Name command = new Name("/localhost/nfd/rib/register");
    command.append(controlParameters.wireEncode());

    try {
      sendCommand(face, command);
    } catch (IOException | EncodingException | ManagementException e) {
      throw new ManagementException(e.getMessage(), e);
    }
  }

  /**
   * Register a route on a forwarder; this will create a new face on the
   * forwarder towards the face (e.g., self registration).
   *
   * @param face  only a localhost {@link Face}
   * @param route the {@link Name} prefix of the route
   * @param cost  the numeric cost of forwarding along the route
   * @throws ManagementException if the network request failed, the NFD response could not be decoded, or
   *                             the NFD rejected the request
   */
  public static void register(final Face face, final Name route, final int cost) throws ManagementException {
    RegistrationOptions options = new RegistrationOptions();
    options.setCapture(false);
    options.setChildInherit(true);

    register(face, new ControlParameters()
      .setName(route)
      .setCost(cost)
      .setOrigin(RouteOrigin.APP.toInteger())
      .setForwardingFlags(options));
  }

  /**
   * Register a route on a forwarder; this will create a new face on the
   * forwarder to the given URI/route pair. See register(Face,
   * ControlParameters) for more detailed documentation.
   *
   * @param face  only a localhost {@link Face}
   * @param uri   the URI (e.g. "tcp4://10.10.2.2:6363") of the remote node; note
   *              that this must be one of the canonical forms described in the wiki
   *              (https://redmine.named-data.net/projects/nfd/wiki/FaceMgmt#TCP) for NFD to
   *              accept the registration--otherwise you will see 400 errors
   * @param route the {@link Name} prefix of the route
   * @param cost  the numeric cost of forwarding along the route
   * @throws ManagementException if the network request failed, the NFD response could not be decoded, or
   *                             the NFD rejected the request
   */
  public static void register(final Face face, final String uri, final Name route, final int cost) throws
    ManagementException {
    // create the new face
    int faceId = createFace(face, uri);

    // run base method
    register(face, faceId, route, cost);
  }

  /**
   * Register a route on a forwarder; this will not create a new face since it
   * is provided a faceId. See register(Face, ControlParameters) for full
   * documentation.
   *
   * @param forwarder only a localhost {@link Face}
   * @param faceId    the ID of the {@link Face} to assign to the route
   * @param route     the {@link Name} prefix of the route
   * @param cost      the numeric cost of forwarding along the route
   * @throws ManagementException if the network request failed, the NFD response could not be decoded, or
   *                             the NFD rejected the request
   */
  public static void register(final Face forwarder, final int faceId, final Name route, final int cost) throws
    ManagementException {
    // build command name
    ControlParameters parameters = new ControlParameters();
    parameters.setName(route);
    parameters.setFaceId(faceId);
    parameters.setCost(cost);
    parameters.setOrigin(RouteOrigin.STATIC.toInteger());
    RegistrationOptions options = new RegistrationOptions();
    options.setCapture(false);
    options.setChildInherit(true);
    parameters.setForwardingFlags(options);

    // run base method
    register(forwarder, parameters);
  }

  /**
   * Unregister a route on a forwarder
   * <p/>
   * Ensure the forwarding face is on the local machine (management requests are to /localhost/...) and that command
   * signing has been set up (e.g. forwarder.setCommandSigningInfo().
   *
   * @param face              only a localhost {@link Face}
   * @param controlParameters the {@link ControlParameters} command options
   * @throws ManagementException if the network request failed, the NFD response could not be decoded, or
   *                             the NFD rejected the request
   * @see <a href="http://named-data.net/doc/NFD/current/manpages/nfdc.html">nfdc</a>
   * @see <a href="https://redmine.named-data.net/projects/nfd/wiki/RibMgmt">RIB Management</a>
   */
  public static void unregister(final Face face, final ControlParameters controlParameters) throws ManagementException {
    // build command name
    Name command = new Name("/localhost/nfd/rib/unregister");
    command.append(controlParameters.wireEncode());

    try {
      sendCommand(face, command);
    } catch (IOException | EncodingException | ManagementException e) {
      throw new ManagementException(e.getMessage(), e);
    }
  }

  /**
   * Unregister a route on a forwarder.
   * <p/>
   * Ensure the forwarding face is on the local machine (management requests are to /localhost/...) and that command
   * signing has been set up (e.g. forwarder.setCommandSigningInfo().
   *
   * @param face  only a localhost {@link Face}
   * @param route the {@link Name} prefix of the route
   * @throws ManagementException if the network request failed, the NFD response could not be decoded, or
   *                             the NFD rejected the request
   * @see <a href="http://named-data.net/doc/NFD/current/manpages/nfdc.html">nfdc</a>
   * @see <a href="https://redmine.named-data.net/projects/nfd/wiki/RibMgmt">RIB Management</a>
   */
  public static void unregister(final Face face, final Name route) throws ManagementException {
    // build command name
    ControlParameters controlParameters = new ControlParameters();
    controlParameters.setName(route);

    // send the interest
    unregister(face, controlParameters);
  }

  /**
   * Unregister a route on a forwarder; see
   * <p/>
   * Ensure the forwarding face is on the local machine (management requests are to /localhost/...) and that command
   * signing has been set up (e.g. forwarder.setCommandSigningInfo().
   *
   * @param face   only a localhost {@link Face}
   * @param route  the {@link Name} prefix of the route
   * @param faceId the specific ID of the face to remove (more than one face can
   *               be registered to a route)
   * @throws ManagementException if the network request failed, the NFD response could not be decoded, or
   *                             the NFD rejected the request
   * @see <a href="http://named-data.net/doc/NFD/current/manpages/nfdc.html">nfdc</a>
   * @see <a href="https://redmine.named-data.net/projects/nfd/wiki/RibMgmt">RIB Management</a>
   */
  public static void unregister(final Face face, final Name route, final int faceId) throws ManagementException {
    // build command name
    ControlParameters controlParameters = new ControlParameters();
    controlParameters.setName(route);
    controlParameters.setFaceId(faceId);

    // send the interest
    unregister(face, controlParameters);
  }

  /**
   * Unregister a route on a forwarder
   * <p/>
   * Ensure the forwarding face is on the local machine (management requests are to /localhost/...) and that command
   * signing has been set up using forwarder.setCommandSigningInfo().
   *
   * @param face  only a localhost {@link Face}
   * @param route the {@link Name} prefix of the route
   * @param uri   the URI (e.g. "tcp4://some.host.com") of the remote node (more
   *              than one face can be registered to a route)
   * @throws ManagementException if the network request failed, the NFD response could not be decoded, or
   *                             the NFD rejected the request
   * @see <a href="http://named-data.net/doc/NFD/current/manpages/nfdc.html">nfdc command-line usage</a>
   * @see <a href="https://redmine.named-data.net/projects/nfd/wiki/RibMgmt">RibMgmt</a>
   */
  public static void unregister(final Face face, final Name route, final String uri) throws ManagementException {
    int faceId = -1;
    for (FaceStatus faceStatus : getFaceList(face)) {
      if (faceStatus.getRemoteUri().matches(uri)) {
        faceId = faceStatus.getFaceId();
        break;
      }
    }

    if (faceId == -1) {
      throw new ManagementException("Face not found: " + uri);
    }

    // send the interest
    unregister(face, route, faceId);
  }

  /**
   * Set a strategy on the forwarder
   * <p/>
   * Ensure the forwarding face is on the local machine (management requests are to /localhost/...) and that command
   * signing has been set up using forwarder.setCommandSigningInfo().
   *
   * @param face     only a localhost {@link Face}
   * @param prefix   the {@link Name} prefix
   * @param strategy the {@link Name} of the strategy to set, e.g.
   *                 /localhost/nfd/strategy/broadcast
   * @throws ManagementException if the network request failed, the NFD response could not be decoded, or
   *                             the NFD rejected the request
   * @see <a href="http://named-data.net/doc/NFD/current/manpages/nfdc.html">nfdc command-line usage</a>
   * @see <a href="https://redmine.named-data.net/projects/nfd/wiki/StrategyChoice">StrategyChoice</a>
   */
  public static void setStrategy(final Face face, final Name prefix, final Name strategy) throws ManagementException {
    // build command name
    Name command = new Name("/localhost/nfd/strategy-choice/set");
    ControlParameters parameters = new ControlParameters();
    parameters.setName(prefix);
    parameters.setStrategy(strategy);
    command.append(parameters.wireEncode());

    try {
      sendCommand(face, command);
    } catch (IOException | EncodingException | ManagementException e) {
      throw new ManagementException(e.getMessage(), e);
    }
  }

  /**
   * Set a strategy on the forwarder; see
   * {@link #setStrategy(net.named_data.jndn.Face, net.named_data.jndn.Name, net.named_data.jndn.Name)}
   * for more information. Ensure the forwarding face is on the local machine
   * (management requests are to /localhost/...) and that command signing has
   * been set up (e.g. forwarder.setCommandSigningInfo()).
   *
   * @param face   only a localhost {@link Face}
   * @param prefix the {@link Name} prefix
   * @throws ManagementException if the network request failed, the NFD response could not be decoded, or
   *                             the NFD rejected the request
   */
  public static void unsetStrategy(final Face face, final Name prefix) throws ManagementException {
    // build command name
    Name command = new Name("/localhost/nfd/strategy-choice/unset");
    ControlParameters parameters = new ControlParameters();
    parameters.setName(prefix);
    command.append(parameters.wireEncode());

    try {
      sendCommand(face, command);
    } catch (IOException | EncodingException | ManagementException e) {
      throw new ManagementException(e.getMessage(), e);
    }
  }

  /**
   * Send an interest as a command to the forwarder; this method will convert
   * the interest to a command interest and block until a response is received
   * from the forwarder. Ensure the forwarding face is on the local machine
   * (management requests are to /localhost/...) and that command signing has
   * been set up (e.g. forwarder.setCommandSigningInfo()).
   *
   * @param face only a localhost Face, command signing info must be set
   * @param name As described at
   *             <a href="https://redmine.named-data.net/projects/nfd/wiki/ControlCommand">ControlCommand</a>,
   *             the requested interest must have encoded ControlParameters appended to the
   *             interest name
   * @return a {@link ControlResponse}
   * @throws IOException         if the network request failed
   * @throws EncodingException   if the NFD response could not be decoded
   * @throws ManagementException if the NFD rejected the request
   */
  private static ControlResponse sendCommand(final Face face, final Name name) throws IOException, EncodingException,
    ManagementException {
    if (face == null) {
      throw new IllegalArgumentException("Face parameter is null.");
    }

    Interest interest = new Interest(name);

    // forwarder must have command signing info set
    try {
      face.makeCommandInterest(interest);
    } catch (SecurityException e) {
      throw new IllegalArgumentException("Failed to make command interest; ensure command signing info is set on the " +
        "face.", e);
    }

    // send command packet
    Data data = FetchHelper.getData(face, interest.getName());

    // decode response
    ControlResponse response = new ControlResponse();
    response.wireDecode(data.getContent().buf());

    // check response for success
    if (response.getStatusCode() != OK_STATUS && response.getStatusCode() != FACE_ALREADY_EXISTS) {
      throw ManagementException.fromResponse(response);
    }

    return response;
  }
}