Hello Edward, Am Fr., 14. Mai 2021 um 14:54 Uhr schrieb Edward K. Ream < [email protected]>:
> The following is pre-writing for a new Chapter in Leo's documentation. > > All comments, suggestions, additions, and corrections are welcome. > > ----- > > leoserver.py is a stand-alone web server that provides access to all of > Leo's capabilities using Leo's bridge. leoserver.py is not part of Leo's > core. > > leoclient.py is an example client, written in python. Clients may be > written in any language. Clients send text requests to the server, in JSON > format, and receive JSON responses from the server. > Would it make sense to ignore mentioning leoclient.py at this point in time completely - or - at least defer mentioning it to the time, when the CP: request / response model has already been described? > This chapter describes how to start the server and the communication > protocol, that is, the format of the JSON requests and responses. > > *Starting the server* > > To start the server, execute `python leoserver.py <args>` in a separate > process, that is, outside of Leo itself. `leoserver -h` prints > "leoserver.py -a <address> -p <port>" > > By default, the server listens on "localhost" and port 32125. You can > change these defaults with the --address and --port command-line arguments. > > *Communication protocol: requests* > > The *_do_message* method expects that incoming requests are JSON objects > that can be converted to a python dict, with the following three keys: > > "id": A positive integer. > > "action": A string, which is either: > - The name of public method of this class, prefixed with a '!'. > - The name of a leo command, without prefix, to be run by > _do_leo_command. > > "param": A dict to be passed to the called "action" method. > *Communication protocol: requests* > A simple copy & paste error: It should read 'response'. > The *_make_response* and *_make_minimal_response* methods return python > dicts that are then converted do JSON. All responses contain an 'id' key > that matches the corresponding requests. > > *Archived positions* > > Leo's Position objects can not be converted directly to JSON. Instead, > requests and response contain *archived positions*, that are strings > representing positions. The server's *_ap_to_p* and *_p_to_ap* methods > convert between real Leo Positions and archived positions. > > *Technical details* > > The *ws_handler *function contains the main server loop. It calls > Python's asyncio.get_event_loop() to start listening on the designated > socket and port. > > ws_handler dispatches incoming requests to the *_do_request* method, > which then dispatches the requests to the appropriate handler, either in > the LeoServer class, or (via Leo's bridge) to Leo itself. > > *Exception handling* > > Request handlers raise ServerError exceptions for badly formatted user > requests. The server returns an response describing the error. > > The server raises InternalServerError for errors within the server itself. > The server prints an error message and stops. > > Request handlers raise TerminateServer to terminate the server normally. > > *Compatibility and future directions* > > The present version of leoserver.py exists to support leoInteg: Leo hosted > on vs code. > > In future, features (request handlers) can be added to leoserver.py, but > features probably will never be removed. > > *Acknowledgements* > > Félix Malboeuf wrote the original version of leoserver.py including the > first draft of the all-important The ws_handler function. Edward K. Ream > helped make the code more pythonic, and provided Leo-specific advice. > With kind regards, Viktor -- You received this message because you are subscribed to the Google Groups "leo-editor" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/leo-editor/CAAeSrGJ2K6PR0bT0Z0RP4mCw%3Dm3OpqQcv0KGGRVZu%3DcqB4EapQ%40mail.gmail.com.
