TODO(ale): update urls

TODO(ale): update URI scheme

cpp-pcp-client is a C++ client library for the PCP protocol. It includes a collection of abstractions which can be used to initiate connections to a PCP server, wrapping the PCP message format and performing schema validation for message bodies.

A tutorial on how to create a PCP agent / controller pair with cpp-pcp-client is here.

• a C++11 compiler (clang/gcc 4.7)
• gnumake
• cmake (2.8.12 or newer)
• boost (1.54 or newer)

Building the library is simple, just run:

make

Tests can be run with:

make test

• Important Data Structures
• Creating Connections
• Message Schemas and Callbacks
• Sending Messages
• Data Validation

The JsonContainer class is used frequently by the cpp-pcp-client library as a simplified abstraction around complex JSON c++ libraries.

ParsedChunks

The Parsed_Chunks struct is a simplification of a parsed PCP message. It allows for direct access of a message's Envelope, Data and Debug chunks as JsonContainer or string objects.

The ParsedChunks struct is defined as:

    struct ParsedChunks {
        // Envelope
        JsonContainer envelope;

        // Data
        bool got_data;
        ContentType data_type;
        JsonContainer data;
        std::string binary_data;

        // Debug
        std::vector<JsonContainer> debug;
    }

    Connector(const std::string& server_url,
              const std::string& client_type,
              const std::string& ca_crt_path,
              const std::string& client_crt_path,
              const std::string& client_key_path)

• client_type - A free form value used to group applications connected to a PCP server. For example, an applications connected with the type potato will all be addressable as the PCP endpoint pcp://*/potato. The only value that you cannot use is "server", which is reserved for PCP servers (please refer to the URI section in the PCP specifications).
• server_url - The URL of the PCP server. For example, wss://localhost:8090/pcp/.
• ca_crt_path - The path to your CA certificate file.
• client_crt_path - The path to a client certificate file generated by your CA.
• client_key_path - The path to a client public key file generated by you CA.

This means that you can instantiate a Connector object as follows:

    Connector connector { "wss://localhost:8090/pcp/", "controller",
                          "/etc/puppet/ssl/ca/ca_crt.pem",
                          "/etc/puppet/ssl/certs/client_crt.pem",
                          "/etc/puppet/ssl/public_keys/client_key.pem" };

When you have created a Connector object you are ready to connect. The Connector's connect method is defined as:

    void connect(int max_connect_attempts = 0) throws (connection_config_error,
                                                       connection_fatal_error)

The parameters are described as:

• max_connect_attempts - The amount of times the Connector will try and establish a connection to the PCP server if a problem occurs. It will try to connect indefinately when set to 0. Defaults to 0.

The connect method can throw the following exceptions:

    class connection_config_error : public connection_error

This exception will be thrown if a Connector is misconfigured. Misconfiguration includes specifying an invalid server url or a path to a file that doesn't exist. Note that if this exception has been thrown no attempt at creating a network connection has yet been made.

    class connection_fatal_error : public connection_error

This exception wil be thrown if the connection cannot be established after the Connector has tried max_connect_attempts times.

A connection can be established as follows:

    try {
        connector.connect(5);
    } catch (connection_config_error e) {
        ...
    } catch (connection_fatal_error) {
        ...
    }

If no exceptions are thrown it means that a connection has been sucessfuly established. You can check on the status of a connection with the Connector's isConnected method.

The isConnected method is defined as:

    bool isConnected()

And it can be used as follows:

    if (connector.isConnected()) {
        ...
    } else {
        ...
    }

By default a connection is non persistent. For instance, in case WebSocket is used as the underlying transport layer, ping messages must be sent periodically to keep the connection alive. Also, the connection may drop due to communication errors. You can enable connection persistence by calling the monitorConnection method that will periodically check the state of the underlying connection. It will send keepalive messages to the server and attempt to re-establish the connection in case it has been dropped.

monitorConnection is defined as:

    void monitorConnection(int max_connect_attempts = 0)

The parameters are described as:

• max_connect_attemps -The number of times the Connector will try to reconnect a connection to the PCP server if a problem occurs. It will try to connect indefinately when set to 0. Defaults to 0.

Note that if the Connector fails to re-establish the connection after the specified number of attempts, a connection_fatal_error will be thrown. Also, calling monitorConnection will block the execution thread as the monitoring task will not be executed on a separate thread. On the other hand, the caller can safely execute monitorConnection on a separate thread since the function returns once the Connector destructor is invoked.

    connector.monitorConnection(5);

    Schema(const std::string& name, ContentType content_type)

    Schema cnc_request_schema { "cnc_request", ContentType::Json};

  {
    "title": "cnc_request",
    "type": "object",
    "properties": {
      "module": {
        "type": "string"
      },
      "action": {
        "type": "string"
      },
    },
    "required": ["module"]
  }

    void addConstraint(std::string field, TypeConstraint type, bool required)

    cnc_request_schema.addConstraint("module", TypeConstraint::String, true);
    cnc_request_schema.addConstraint("action", TypeConstraint::String);

    void registerMessageCallback(const Schema schema, MessageCallback callback)

    void cnc_requestCallback(const ParsedChunks& msg_content) {
      std::cout << "Message envelope: " << msg_content.envelope.toString() << std::endl;

      if (msg_content.has_data()) {
        if (msg_content.data_type == ContentType::Json) {
          std::cout << "Content Type: JSON" << std::endl;
          std::cout << msg_content.data.toString() << std::endl;
        } else {
          std::cout << "Content Type: Binary" << std::endl;
          std::cout << msg_content.binary_data << std::endl;
        }
      }

      for (const auto& debug_chunk : msg_content) {
        std::cout << "Data Chunk: " << debug_chunk << std::endl;
      }
    }

    ...
    connector.registerMessageCallback(cnc_request_schema, cnc_requestCallback);

    connector.registerMessageCallback(cnc_request_schema, cnc_requestCallback);
    connector.registerMessageCallback(puppet_request_schema, puppet_requestCallback);
    connector.registerMessageCallback(puppet_db_request_schema, puppet_db_requestCallback);

    connector.registerMessageCallback(schema_1, genericCallback);
    ...
    connector.registerMessageCallback(schema_n, genericCallback);
    connector.registerMessageCallback(schema_n1, genericCallback);

    void send(std::vector<std::string> targets,
              std::string data_schema,
              unsigned int timeout,
              JsonContainer data_json,
              std::vector<JsonContainer> debug = std::vector<JsonContainer> {})
                        throws (connection_processing_error, connection_not_init_error)

    void send(std::vector<std::string> targets,
              std::string data_schema,
              unsigned int timeout,
              std::string data_binary,
              std::vector<JsonContainer> debug = std::vector<JsonContainer> {})
                        throws (connection_processing_error, connection_not_init_error)

    class connection_processing_error : public connection_error

    class connection_not_init_error : public connection_error

    JsonContainer data {};
    data.set<std::string>("foo", "bar");
    try {
      connector.send({"pcp://*/potato"}, "potato_schema", 42, data);
    } catch (connection_not_init_error e) {
      std::cout << "Cannot send message without being connected to the server" << std::endl;
    } catch (connection_processing_error e) {
      std::cout << "An error occured at the WebSocket layer: " << e.what() << std::endl;
   }

As mentioned in the Message Schemas and Callbacks, messages received from the PCP server will be matched against a Schema that you defined. The Connector object achieves this functionality by using an instance of the Validator class. It is possible to instantiate your own instance of the Validator class and use schema's to validate other, non message, data structures.

The Validator is limited to a no-args constructor:

    Validator()

You can register a Schema by using the registerSchema method, defined as:

    void registerSchema(const Schema& schema) throws (schema_redefinition_error)

The parameters are described as follows:

• schema - A schema object that desribes a set of constraints.

When a Schema has been registered you can use the validate method to validate a JsonContainer object. The validate method is defined as follows:

    void validate(JsonContainer& data, std::string schema_name) const throws (validation_error)

The parameters are described as follows:

• data - A JsonContainer you want to validate.
• schema_name - The name of the schema you want to validate against.

Example usage:

    Validator validator {};
    Schema s {"test-schema", ContentType::Json };
    s.addConstraint("foo", TypeConstraint::Int);
    validator.registerSchema(s);

    JsonContainer d {};
    d.set<int>("foo", 42);

    try {
      Validator.validate(d, "test-schema");
    } catch (validation_error) {
      std::cout << "Validation failed" << std::endl;
    }