Re: Api idés

Hi Patrik,

When checking keepaliveds snmp modul,  i found it quit near what a low 
level api
needs !.

Only needed to add abstractions level a bit and restore ascii style api 
functions in library.

Reuse code from that, and lift out snmp as a separate modul, like cli.
and exend with write/config tokens and api developer save some time.


2015-05-07 14:55 skrev jan:
> 2015-05-07 08:16 skrev Patrick Schaaf:
>> I think a binary, RLE API would be way over the top. This is in no way
>> performance critical. A text stream based API is way easier to develop
>> against, and debug.
> 
> Binary is for one reason speed, think if you get data for graphic
> purpose
> for every interface, it will be a hug overload to send that in ascii
> format.
> 
> Updates every 1/10 seconds, packet p/s for tx / rx and actual size.
> 
> 10 interface and 10 graph it would not be optimal to send in ascii.
> 
> For a CLI applications it's overkill you don't need that performance.
> 
> Programmer to develop a cli or other tools need a library to 
> encapsulate
> low level RLE to "high level ascii land" and developer never need to
> care about any RLE stuff at all, use command/tokens in ascii format as
> normal to
> library routines instead.
> 
>> Some rough notes on how that could look:
>> 
>> 1) Overall structure of communication:
>> 
>> Transport over UNIX domain socket (no auth required by default), or
>> TCP (auth required).
> 
> Agree
> 
>> Daemon never sends anything unless provoked (sent a command line).
>> What the daemon sends in response to a command, depends on the
>> command. All sent commands and replies are n or rn terminated text
>> lines (no fancy encoding - or is there any need for that that I can't
>> see?).
> 
> But if you wont to monitor something like logfile you should get
> that with a single command, not repeted (like polled),send until "stop
> send log file"
> or socket close for any reason.
> 
> should work like "tail -f /var/log/keepalved.log"
> 
>> Command lines sent to the daemon are space separated token sequences.
>> They all start with a keyword, further tokens are interpreted
>> accordingly.
> 
> Agree if its a CLI application,
> You need /keyword/next_token ... or /keyword next_token ...
> 
> If you are in interface level and want to do "/ip ro sh"
> to display all routes without to be in top level.
> 
> 
>> Replies, when expected, all start with a keyword (indicating success,
>> failure, what it expected next for modal stuff), with the rest of the
>> line purely informational. These reply keywords are chosen to NEVER be
>> valid first keywords of configuration or status output lines (stuff
>> that would appear in show commands that we'd want to be easily
>> copy+pasteable)
>> 
>> Any request or reply keyword is documented and interpreted case
>> sensitive. Programmers should not need to do case conversion to
>> recognize stuff.
> 
> Agree
> 
>> 2) Authentication and Authorization
>> 
>> When required (*), the first thing a client MUST do is authenticate.
>> If the client thinks it does not need to authenticate, but it should,
>> its first command, unless it starts an authentication, elicits a
>> response, e.g. "AUTH-FAIL", and the daemon drops the connection
>> immediately afterwards.
>> 
>> Authentication starts with a command "auth user <USERNAME>". That will
>> always elicit a response:
>>  * "AUTHENTICATED <AUTHORIZATION-LIST*>" when no authentication is
>> required. Client may proceed, and use any of the commands covered by
>> the space-separated list of authorization tokens (may be stuff like
>> CONFIG, SHOW, SHUTDOWN, ... and all commands should clearly document
>> which authorization tokens are required to use them).  This kind of
>> reply is also used when a user that needs authentication, has
>> successfully completed it.
>>  * "AUTH-NEEDED <SCHEMES+>" when further authentication is needed;
>> lists, space separated, authentication schemes permitted. NOTE: this
>> list MUST reflect what configuration allows, and MUST NOT vary
>> depending on the <USERNAME> from the request.
>> 
>> When AUTH-NEEDED, client then sends "auth scheme <SCHEME>
>> <CREDENTIALS*>". For schemes that don't need further steps, an
>> AUTHENTICATED reply (see above) is sent when the credentials were
>> good, or "AUTH-FAIL" and connection close otherwise. For schemes that
>> require further steps, a reply of "AUTH-CHALLENGE <SCHEME>
>> <whatever*>" is sent, and the client is expected to send another "auth
>> scheme <SCHEME> <CREDENTIALS*>" line to complete.
>> 
>> Once the client successfully authenticated, it knows that it can do
>> (via the AUTHORIZATION-LIST from the AUTHENTICATED reply.) Maybe the
>> client further would like to authenticate the daemon - that could be
>> requested with an "auth yourself <...>" command, won't go into details
>> now.
>> 
>> Auth _configuration_ should be only possible with suitable privilege,
>> only shown (when listing config) with suitable privilege; auth
>> credentials ALWAYS separate from online modifiable configuration
>> (separate config file - no need to be easy to change on the fly)
> 
> Need only 3 level: write access, read access, both read/write
> in low level api.
> 
> Always send salt value in reply cmd with a plain login
> 
> Login with name and password a second time and you have access
> read/write/both
> 
> 
>> 3) Command Discovery
>> 
>> For the benefit of CLI clients supporting autocompletion, it might be
>> interesting to implement a discovery mechanism regarding commands
>> supported by the daemon. Thinking along these lines:
> 
> Agree
> 
> CLI program should ask all cmds and argument from low level api in
> initialization task.
> 
> 
>> * "info commands" would result in a multiline reply. Each line starts
>> with "COMMAND " followed by a single valid command syntax.
>> Placeholders there, e.g. <IP>, would indicate variable parts of the
>> command. The list is terminated by a line starting / reading
>> "COMMAND-END".
>>  * "info version" would result in a single line reply "VERSION
>> <daemon-version-number>
>> <hash-of-valid-command-defining-config-parts>". This would be good for
>> the benefit of CLI clients to be able to cache "info commands" replies
>> - the CLI could keep the command list for the given authenticated user
>> for as long as the daemon-version-number and hash doesn't change.
>> 
>> 4) Configuration Changes
>> 
>> Using a "configure" command, the client indicates it wants to change
>> configuration. This mail is already too long, though, so I'll stop
>> here :)
> 
> 
>> best regards
>>    Patrick
> 
> --
> 
> best regarding
> 
> /Jan Holmberg
> 
> ------------------------------------------------------------------------------
> One dashboard for servers and applications across 
> Physical-Virtual-Cloud
> Widest out-of-the-box monitoring support with 50+ applications
> Performance metrics, stats and reports that give you Actionable 
> Insights
> Deep dive visibility with transaction tracing using APM Insight.
> http://ad.doubleclick.net/ddm/clk/290420510;117567292;y
> _______________________________________________
> Keepalived-devel mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/keepalived-devel

-- 

mvh

/Jan Holmberg

------------------------------------------------------------------------------
One dashboard for servers and applications across Physical-Virtual-Cloud 
Widest out-of-the-box monitoring support with 50+ applications
Performance metrics, stats and reports that give you Actionable Insights
Deep dive visibility with transaction tracing using APM Insight.
http://ad.doubleclick.net/ddm/clk/290420510;117567292;y