diff --git a/README.md b/README.md index 2e2aa91..a872188 100644 --- a/README.md +++ b/README.md @@ -107,7 +107,7 @@ ctrl supports both the use of flags with env variables. An .env file can also be ### Schema for the messages to send into ctrl via the API's -|Name | value | description| +|Field Name | Value Type | Description| |-----|-------|------------| |toNode | `string` | A single node to send a message to| |toNodes | `string array` | A comma separated list of nodes to send a message to| diff --git a/doc/book/core_messaging_message_fields.html b/doc/book/core_messaging_message_fields.html new file mode 100644 index 0000000..65803f5 --- /dev/null +++ b/doc/book/core_messaging_message_fields.html @@ -0,0 +1,287 @@ + + + + + + Message fields - ctrl + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+

Message fields

+
toNode : "some-node"
+
+

The node to send the message to.

+
toNodes : node1,node2
+
+

ToNodes to specify several hosts to send message to in the form of an slice/array. When used, the message will be split up into one message for each node specified, so the sending to each node will be handled individually.

+
data : data here in byte format
+
+

The actual data in the message. This is the field where we put the returned data in a reply message. The data field are of type []byte.

+
method : REQCliCommand
+
+

What request method type to use, like REQCliCommand, REQHttpGet..

+
  methodArgs :
+  - "bash"
+  - "-c"
+  - |
+      echo "this is a test"
+      echo "and some other test"
+
+

Additional arguments that might be needed when executing the method. Can be f.ex. an ip address if it is a tcp sender, or the actual shell command to execute in a cli.

+
replyMethod : REQToFile
+
+

ReplyMethod, is the method to use for the reply message. By default the reply method will be set to log to file, but you can override it setting your own here.

+
  methodArgs :
+  - "bash"
+  - "-c"
+  - |
+      echo "this is a test"
+
+

Additional arguments that might be needed when executing the reply method. Can be f.ex. an ip address if it is a tcp sender, or the shell command to execute in a cli session. +replyMethodArgs :

+
fromNode Node : "node2"
+
+

From what node the message originated. This field is automatically filled by ctrl when left blanc, so that when a message are sent from a node the user don't have to worry about getting eventual repply messages back. +Setting a

+
ACKTimeout: 10 
+
+

ACKTimeout for waiting for an Ack message in seconds.

+

If the ACKTimeout value is set to 0 the message will become an No Ack message. With No Ack messages we will not wait for an Ack, nor will the receiver send an Ack, and we will never try to resend a message.

+
retryWait : 60
+
+

RetryWait specifies the time in seconds to wait between retries. This value is added to the ACKTimeout and to make the total time before retrying to sending a message. A usecase can be when you want a low ACKTimeout, but you want to add more time between the retries to avoid spamming the receiving node.

+
retries : 3
+
+

How many times we should try to resend the message if no ACK was received.

+
replyACKTimeout int `json:"replyACKTimeout" yaml:"replyACKTimeout"`
+
+

The ACK timeout used with reply messages. If not specified the value of ACKTimeout will be used.

+
replyRetries int `json:"replyRetries" yaml:"replyRetries"`
+
+

The number of retries for trying to resend a message for reply messages.

+
methodTimeout : 10
+
+

Timeout for how long a method should be allowed to run before it is timed out.

+
replyMethodTimeout : 10
+
+

Timeout for how long a method should be allowed to run before it is timed out, but for the reply message.

+
directory string `json:"directory" yaml:"directory"`
+
+

Specify the directory structure to use when saving the result data for a repply message.

+
    +
  • When the values are comma separated like "syslog","metrics" a syslog folder with a subfolder metrics will be created in the directory specified with startup env variable SUBSCRIBER_DATA_FOLDER.
    • +
  • Absolute paths can also be used if you want to save the result somewhere else on the system, like "/etc/myservice".
    • +
+
fileName : myfile.conf
+
+

The fileName field are used together with the directory field mentioned earlier to create a full path for where to write the resulting data of a repply message.

+
schedule : [2,5]
+
+

Schedule are used for scheduling the method of messages to be executed several times. The schedule is defined as an array of two values, where the first value defines how often the schedule should trigger a run in seconds, and the second value is for how long the schedule are allowed to run in seconds total. [2,5] will trigger the method to be executed again every 2 seconds, but when a total time of 5 seconds have passed it will stop scheduling.

+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + + + +
+ + diff --git a/doc/book/user_guide.html b/doc/book/core_messaging_overview.html similarity index 73% rename from doc/book/user_guide.html rename to doc/book/core_messaging_overview.html index 31633b3..fa77ea7 100644 --- a/doc/book/user_guide.html +++ b/doc/book/core_messaging_overview.html @@ -3,7 +3,7 @@ - User Guide - ctrl + Messaging - ctrl @@ -152,16 +152,39 @@
- +

Messaging

+

The handling of all messages is done by spawning up a process for handling the message in it's own thread. This allows us to keep the state of each individual message level both in regards to ACK's, error handling, send retries, and reruns of methods for a message if the first run was not successful.

+

All messages processed by a publisher will be written to a log file after they are processed, with all the information needed to recreate the same message if needed, or it can be used for auditing.

+

All handling down to the process and message level are handled concurrently. So if there are problems handling one message sent to a node on a subject it will not affect the messages being sent to other nodes, or other messages sent on other subjects to the same host.

+

Message types of both ACK and NACK, so we can decide if we want or don't want an Acknowledge if a message was delivered succesfully. +Example: We probably want an ACK when sending some REQCLICommand to be executed, but we don't care for an acknowledge NACK when we send an REQHello event. +If a message are ACK or NACK type are defined by the value of the ACKTimeout for each individual message:

+ +

If ACK is expected, and not received, then the message will be retried the amount of time defined in the retries field of a message. If numer of retries are reached, and still no ACK received, the message will be discared, and a log message will be sent to the log server.

+

To make things easier, all timeouts used for messages can be set with env variables or flags at startup of ctrl. Locally specified timeout directly in a message will override the startup values, and can be used for more granularity when needed.

+

Example of message flow:

+ + + +

+ +
diff --git a/doc/book/index.html b/doc/book/index.html index 6539a67..a0af4cf 100644 --- a/doc/book/index.html +++ b/doc/book/index.html @@ -172,7 +172,7 @@ sender.