diff --git a/notes/project.asciidoc b/notes/project.asciidoc new file mode 100644 index 0000000..5a36821 --- /dev/null +++ b/notes/project.asciidoc @@ -0,0 +1,136 @@ += Project features + +This page list all final user case. All these features are currently +not or partialy implemented. + +== Coding rules + + * Please, respect developpers! Don't make long lines, maximum 80 + chars, best to 70 chars. + + * Strict rfc3164 implementation, read, and reread this RFC and + current implementation in other language. + + * Create specification and unit test + + * Don't repeat yourself, create macro. + + * Use emacs with emacs-mode + + * Try to test with older and current implementation of rsyslog, + syslogng and GNU/BSD implementation + + * testing branch is unstable and was created only for test, push in + it when you have done something + + * Merge in master branch ONLY when: + + ** All functions has specification + ** All functions has unit test (and pass test) + ** All functions has updated documentation + ** Benchmark your code based on unit test + +== Encoding + + * Respect strictly rfc3164 encoding + + * Multiple way to encode syslog message + +[erlang] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +// as map +rfc3164:encode(#{}). + +// as proplist +rfc3164:encode([]). + +// as record +rfc3164:encode(#rfc3164{}). +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + * Define good value by default if not defined + +[erlang] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Data = #{ priority => <<"13">> }, +rfc3164:encode(Data). +// return: +// <<"<13>Jan 1 12:13:14 hostname tag[123]: empty message">>. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + * Allowing control on output + +[erlang] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Data = #{ hostname => "test" }, +Options = [{with, [message]}, {without, [year, tag]}] +rfc3164:encode(Data, Options). +// return: +// <<"<13>Jan 1 12:13:14 test: empty message">> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + * Allow multiple way to set value + +[erlang] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Data = #{ facility => 0, severity => emerg, message => "alert!" }, +Data2 = #{ facility => kern, severity => 0, message => "alert!" }, +rfc3164:encode(Data). +rfc3164:encode(Data2). +// return same value: +// <<"<0>Jan 1 12:13:14 hostname tag[123]: alert!">>. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +== Decoding + + * Multiple way to decode message + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +// as proplist +rfc3164:decode(Packet, [{export, as_list}]). + +// as map +rfc3164:decode(Packet, [{export, as_map}]). + +// as record +rfc3164:decode(Packet, [{export, as_record}). +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + * Extract only required values on raw packet + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Options = [{extract, [priority, tag]} + ,{export, as_map}], +rfc3164:decode(Packet, Options). +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + * Allow strict and permissive decoding + +## Validation + + * Validate packet if its could be an rfc3164 implementation message, + returning error/warning. + +[erlang] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +rfc3164:check(RawPacket). +// return: +// ok +// or: +// {warning, [{header, unicode}] +// or: +// {error, [priority]} +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +## Scrub + + * Scrub packets and create good one based on rfc3164. + + * Correct header (unicode and more) + + * Packet size check + +## Portability + + * some datastructure (maps) are not supported in all Erlang release, + disable it when Erlang is built for old release. diff --git a/notes/project.md b/notes/project.md deleted file mode 100644 index d8a3be5..0000000 --- a/notes/project.md +++ /dev/null @@ -1,117 +0,0 @@ -# Project features - -This page list all final user case. All these features are -currently not or partialy implemented. - -## Coding rules - - * Please, respect developpers! Don't make long lines, maximum 80 - chars, best to 70 chars. - - * Strict rfc3164 implementation, read, and reread this - RFC and current implementation in other language. - - * Create specification and unit test - - * Don't repeat yourself, create macro. - - * Use emacs with emacs-mode - - * Try to test with older and current implementation of rsyslog, - syslogng and GNU/BSD implementation - - * testing branch is unstable and was created only for test, - push in it when you have done something - - * Merge in master branch ONLY when: - - * All functions has specification - * All functions has unit test (and pass test) - * All functions has updated documentation - * Benchmark your code based on unit test - -## Encoding - - * Respect strictly rfc3164 encoding - - * Multiple way to encode syslog message - - // as map - rfc3164:encode(#{}). - - // as proplist - rfc3164:encode([]). - - // as record - rfc3164:encode(#rfc3164{}). - - * Define good value by default if not defined - - Data = #{ priority => <<"13">> }, - rfc3164:encode(Data). - // return: - // <<"<13>Jan 1 12:13:14 hostname tag[123]: empty message">>. - - * Allowing control on output - - Data = #{ hostname => "test" }, - Options = [{with, [message]}, {without, [year, tag]}] - rfc3164:encode(Data, Options). - // return: - // <<"<13>Jan 1 12:13:14 test: empty message">> - - * Allow multiple way to set value - - Data = #{ facility => 0, severity => emerg, message => "alert!" }, - Data2 = #{ facility => kern, severity => 0, message => "alert!" }, - rfc3164:encode(Data). - rfc3164:encode(Data2). - // return same value: - // <<"<0>Jan 1 12:13:14 hostname tag[123]: alert!">>. - -## Decoding - - * Multiple way to decode message - - // as proplist - rfc3164:decode(Packet, [{export, as_list}]). - - // as map - rfc3164:decode(Packet, [{export, as_map}]). - - // as record - rfc3164:decode(Packet, [{export, as_record}). - - * Extract only required values on raw packet - - Options = [{extract, [priority, tag]} - ,{export, as_map}], - rfc3164:decode(Packet, Options). - - * Allow strict and permissive decoding - -## Validation - - * Validate packet if its could be an rfc3164 implementation - message, returning error/warning. - - rfc3164:check(RawPacket). - // return: - // ok - // or: - // {warning, [{header, unicode}] - // or: - // {error, [priority]} - -## Scrub - - * Scrub packets and create good one based on rfc3164. - - * Correct header (unicode and more) - - * Packet size check - -## Portability - - * some datastructure (maps) are not supported in all Erlang - release, disable it when Erlang is built for old release.