Initial commit

.gitignore

@@ -0,0 +1,3 @@
+.*.swp
+__pycache__
+config.ini

README.md

@@ -0,0 +1,88 @@
+# PyWSClock
+
+Websocket clock server, handling timezones and alarms.
+
+## Dependencies
+
+* Python >= 3.9
+* python3-dateutil 2.8.1
+* python3-websockets 8.1
+
+**Debian-based dependencies installation**
+
+`apt install python3-dateutil python3-websockets`
+
+**Installing dependencies using pip**
+
+`pip3 install -r requirements.txt`
+
+## Running the server
+
+`python3 -m pyws_clock`
+
+Get some help using `python3 -m pyws_clock --help`
+
+## Deployment
+
+Systemd service will run the server using the `run_server.sh` script. This
+script runs `python3 -m pyws_clock -C config.ini` allowing to configure the
+daemon with a `config.ini` file.
+
+### Create a configuration file
+
+`cp config.ini.inc config.ini; edit config.ini`
+
+### Create a systemd service
+
+```sh
+cp pyws_clock.service.inc pyws_clock.service
+edit pyws_clock.service
+cp pyws_clock.service /etc/systemd/system/
+systemctl enable pyws_clock.service
+systemctl start pyws_clock.service
+systemctl status pyws_clock.service
+```
+
+### Testing the websocket server
+
+Run this command and send a dummy session id by pressing enter.
+`python3 -m websockets ws://127.0.0.1:8901`
+
+### Example deployment on Debian 11
+
+```sh
+adduser --system pyws_clock
+cp -R pyws_clock /home/pyws_clock/
+cd /home/pyws_clock/pyws_clock/
+
+cp config.ini.inc config.ini
+echo "session_directory=/var/run/pyws_clock/sessions/
+logfile=/var/log/pyws_clock/pyws_clock.log" >> config.ini
+
+cp pyws_clock.service.inc pyws_clock.service
+echo -e "User=pyws_clock
+Group=nogroup
+WorkingDirectory=/home/pyws_clock/pyws_clock/
+ExecStart=/home/pyws_clock/pyws_clock/run_server.sh" >> pyws_clock.service
+mv pyws_clock.service /etc/systemd/system/
+
+# log dir & rotation config
+mkdir /var/log/pyws_clock/
+chown pyws_clock: /var/log/pyws_clock
+cp logrotate_pyws_clock.inc /etc/logrotate.d/pyws_clock
+systemctl restart logrotate
+
+# session directory creation
+mkdir -p /var/run/pyws_clock/sessions/
+chown -R pyws_clock: /var/run/pyws_clock
+
+# Enabling & starting the systemd service
+systemctl enable pyws_clock.service
+systemctl start pyws_clock.service
+systemctl status pyws_clock.service
+```
+
+### Nginx configuration
+
+A sample configuration is available in `nginx_server.conf`.
+

config.ini.inc

@@ -0,0 +1,11 @@
+[pyws_clock]
+# Listen on given TCP port
+port=8901
+# Bind to TCP address (0.0.0.0 for any)
+listen=127.0.0.1
+## Uncomment the line bellow to activate file sessions stored in given directory
+#session_directory=/var/run/pyws_clock/sessions/
+# Loglevels : 0 WARNING, 1 INFO, 2 DEBUG
+loglevel=1
+## Uncomment the line bellow to log in a file instead of stderr 
+#logfile=/var/log/pyws_clock/pyws_clock.log

logrotate_pyws_clock.inc

@@ -0,0 +1,7 @@
+/var/log/pyws_clock/*.log {
+    daily
+    missingok
+    rotate 7
+    compress
+    copytruncate
+}

nginx_server.conf

@@ -0,0 +1,24 @@
+server {
+        listen 80 default_server;
+        listen [::]:80 default_server;
+
+        root /var/www/clock/;
+
+        index index.html;
+
+        server_name _;
+
+        location / {
+                try_files $uri $uri/ =404;
+        }
+
+        location /wsclock/ {
+                proxy_pass http://127.0.0.1:8901;
+                proxy_http_version 1.1;
+                proxy_set_header X-Real-IP $remote_addr;
+                proxy_set_header Upgrade $http_upgrade;
+                proxy_set_header Connection "Upgrade";
+                proxy_set_header Host $Host;
+        }
+
+}

pyws_clock.service.inc

@@ -0,0 +1,15 @@
+[Unit]
+Description=Websocket clock server
+After=network.target
+
+[Install]
+WantedBy=multi-user.target
+
+[Service]
+Type=simple
+## You have to set the config bellow
+#User=SOMEUSER
+#Group=SOMEGROUP
+#WorkingDirectory=/SOMEDIR/pyws_clock/
+#ExecStart=/SOMEDIR/pyws_clock/run_server.sh
+

pyws_clock/__init__.py

@@ -0,0 +1,2 @@
+from . import command
+from . import commands

pyws_clock/__main__.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+
+import argparse
+import asyncio
+import logging
+from logging.handlers import WatchedFileHandler
+
+import websockets
+
+from .command import Command
+from .config import parse_config
+from .server import websocket_handler
+from .session import Session
+
+async def main(listen_addr:str, port:int):
+    """ Create the websocket and handle new connection with websocket_handler
+    """
+    logging.warning('Listening on %s:%d' % (listen_addr, port))
+    async with websockets.serve(websocket_handler, listen_addr, port):
+        await asyncio.Future()
+
+def cli():
+    """ Run CLI """
+    proto_desc = '''
+Before entering the main loop, the listening server waits for 1st message
+containing a session ID. If an empty/dummy/invalid session ID is sent by the
+client, the server replies with a new, valid, session ID and enter the main loop.
+If a valid session ID is sent, the server reply the same session ID and enter
+the main loop, formated using SESSION:<SESSION_ID>.
+
+
+Main loop :
+-----------
+
+The server send the current time (ISO 8601 format) every second.
+
+Command results :
+-----------------
+
+The client can interact with the server sending one of the command listed using
+the -L flag.
+
+When a client send a command, the next message from the server will be a command
+result. Results are string formatted using <STATUS>:<DETAILS>. Status can be
+one of 'ERR' or 'OK', details are optionnale for OK statuses.
+
+Alarms rings :
+--------------
+
+When an alarm is ringing, after sending time, the server send messages formatted
+using ALRM:<JSON_ARRAY> where JSON_ARRAY is a JSON array containing the name of
+the ringin alarms.
+
+Timezone informations :
+-----------------------
+
+Before the first time is sent and every time the timezone changes (inclucing
+summer/winter transitions), the clock. Timezones messages are formatted using
+TZN:<TZNAME>
+
+Messages types summary :
+------------------------
+Session ID
+    SESSION:<SESSION_ID>
+Clock tick
+    ISO8601_Datetime
+Timezone name
+    TZN:<TZNAME>
+Alarm rings
+    ALRM:<JSON_ARRAY>
+Command results
+    OK:<DETAILS>
+    ERR:<REASON>
+'''
+    parser = argparse.ArgumentParser(description='Run a simple clock websocket \
+server sending time every seconds', epilog=proto_desc,
+formatter_class=argparse.RawDescriptionHelpFormatter)
+
+    parser.add_argument('-C', '--config', default=None,
+                        help="Indicate a config.ini file")
+    parser.add_argument('-p', '--port', default=80, type=int,
+                        help='The TCP port to listen to')
+    parser.add_argument('-l', '--listen-address', default='localhost', type=str,
+                        help='Bind to this address (localhost by default)')
+    parser.add_argument('-L', '--list-commands', default=False,
+                        action='store_true',
+                        help='List available commands on the websocket and exit')
+    parser.add_argument('-H', '--help-command', metavar='CMD',
+                        choices=Command.list()+['ALL'],
+                        help='Print a command help and exit')
+    parser.add_argument('-v', '--verbose', action='count', default=0,
+                        help='Increase verbosity level')
+    parser.add_argument('-F', '--file-session', action="store_true", default=False,
+                        help="Use persistent file session instead of RAM session")
+    parser.add_argument('-S', '--session-dir', type=str, default=None,
+                        help="Store session in given directory (implies -F)")
+    parser.add_argument('--logfile', type=str,
+                        help="Log to given file instead of stderr")
+
+    args = parser.parse_args()
+
+    if args.config:
+        parse_config(args.config, args)
+
+    loglvls = [logging.WARN, logging.INFO, logging.DEBUG]
+    if args.verbose >= len(loglvls):
+        lvl = loglvls[-1]
+    else:
+        lvl = loglvls[args.verbose]
+    bconfig_kwargs = {'level':lvl,
+                      'format':'%(asctime)s %(levelname)s:%(message)s'}
+    if args.logfile:
+        bconfig_kwargs['handlers'] = [WatchedFileHandler(args.logfile)]
+    logging.basicConfig(**bconfig_kwargs)
+
+    if args.file_session or args.session_dir:
+        Session.set_file_handler(args.session_dir)
+
+    all_cmd = Command.all()
+    if args.list_commands:
+        for cmd in all_cmd.values():
+            usage = ':'.join(cmd.usage.split(':')[1:]).strip()
+            print('# %s\n\t%s' % (cmd.description, usage))
+        exit(0)
+
+    if args.help_command:
+        if args.help_command == 'ALL':
+            print(('-'*16).join([cmd.help
+                                 for cmd in all_cmd.values()]))
+            exit(0)
+        if args.help_command not in all_cmd:
+            logging.critical('Unknown command %r' % args.help_command)
+            exit(1)
+        print(all_cmd[args.help_command].help)
+        exit(0)
+
+    asyncio.run(main(args.listen_address, args.port))
+
+if __name__ == '__main__':
+    cli()

pyws_clock/clock.py

@@ -0,0 +1,114 @@
+import datetime
+
+import dateutil
+import dateutil.tz
+
+from .errors import AlarmNameError
+from .session import Session
+from .clock_alarm import ClockAlarm
+
+
+class Clock(object):
+    """ Represents a timezone aware clock with programmable alarms """
+
+    def __init__(self, session_id=None, tzname:str='UTC'):
+        """ Instanciate a new clock
+            @param tzname : the name of the timezone (UTC for UTC)
+        """
+        self.__session = Session.get(session_id)
+        if 'tzname' in self.__session:
+            tzname = self.__session['tzname']
+        else:
+            self.__session['tzname'] = tzname
+
+        self.__tzname = tzname
+        self.__tz = None
+        if 'alarms' not in self.__session:
+            self.__session['alarms'] = dict()
+        self.alarms = self.__session['alarms'] # updated by reference
+
+        self.set_tz(self.__tzname)
+
+    @property
+    def tz(self) -> datetime.tzinfo:
+        """ Returns the clock tzinfo """
+        return self.__tz
+
+    @property
+    def tzname(self) -> str:
+        """ Returns the clock timezone name """
+        tzn1 = datetime.datetime.now(tz=self.__tz).tzname()
+        tzn2 = self.__tzname
+        return tzn1 if tzn1 == tzn2 else '%s(%s)' % (tzn2, tzn1)
+
+    @property
+    def utcoffset(self) -> int:
+        """ Returns utcoffset in seconds """
+        return datetime.datetime.now(tz=self.__tz).utcoffset()
+
+    @property
+    def session_id(self) -> str:
+        """ Returns the sesison id """
+        return self.__session.session_id
+
+    def now(self) -> datetime.datetime:
+        """ Return the clock localtime """
+        self.__session.tick()
+        now_dt = datetime.datetime.now(tz=self.__tz).replace(microsecond=0)
+        for alrm in self.alarms.values():
+            alrm.is_ringing()
+        return now_dt
+
+    def set_tz(self, tzname:str) -> bool:
+        """ Set the clock timezone from dateutil.tz.gettz
+            @param tzname : the name of the timezone (UTC for UTC)
+            @return True if timezone found else False
+        """
+        newtz = dateutil.tz.gettz(tzname)
+        if newtz is None:
+            return False
+        self.__tzname = tzname
+        self.__tz = dateutil.tz.gettz(tzname)
+        self.__session['tzname'] = self.__tzname
+        return True
+
+    def alarm_add(self, name:str) -> None:
+        """ Add an alarm to the clock
+            @param name : alarm name,must be unique
+            @throws AlarmNameError if name is not unique or empty
+        """
+        if name in self.alarms:
+            raise AlarmNameError('There is allready an alarm %r' % name)
+        self.alarms[name] = ClockAlarm()
+
+    def alarm_del(self, name:str) -> None:
+        """ Delete an alarm from the clock
+            @param name : the alarm name
+            @throws AlarmNameError if alarm not found
+        """
+        if name not in self.alarms:
+            raise AlarmNameError('There is no alarm %r' % name)
+        del self.alarms[name]
+
+    def alarm_get(self, name:str) -> None:
+        """ Return an alarm given its name
+            @param name : the alarm name
+            @throws AlarmNameError if alarm not found
+        """
+        if name not in self.alarms:
+            raise AlarmNameError('There is no alarm %r' % name)
+        return self.alarms[name]
+
+    def alarm_rings(self) -> list:
+        """ Return ringing alarm's names
+            @return a list of strings
+        """
+        return [name for name, alrm in self.alarms.items()
+                if alrm.is_ringing()]
+
+    def alarm_snooze(self, minutes:float=15) -> None:
+        """ Snooze all ringing alarms
+            @param minutes : snooze for this amount of minutes
+        """
+        for name in self.alarm_rings():
+            self.alarms[name].snooze(minutes)

pyws_clock/clock_alarm.py

@@ -0,0 +1,132 @@
+import datetime
+import json
+
+import dateutil
+
+utctz = datetime.timezone.utc
+
+class ClockAlarm(object):
+    """ Represent an alarm """
+
+    def __init__(self, _utcnow=lambda: datetime.datetime.now(tz=utctz)):
+        """ Instanciate a new alarm
+            @param _utcnow : a function returning current UTC datetime
+        """
+        self.__utcnow = _utcnow
+        self._time = datetime.time(0, 0, 0, tzinfo=datetime.timezone.utc)
+        self._ringing = False
+        self._next_ring = None
+        self._snooze = False
+
+    @property
+    def is_on(self) -> bool:
+        """ @return True if the alarm is on (will ring) else False """
+        return self._next_ring is not None
+
+    @property
+    def json(self) -> str:
+        """ @return a json representation of the instance """
+        ret = {'time':self._time.isoformat(), 'ringing':self._ringing,
+               'snooze':self._snooze}
+        if self._next_ring:
+            ret['next_ring']  = self._next_ring.isoformat()
+        return json.dumps(ret)
+
+    def _from_json(self, data:str):
+        """ Load internal state from json (as given by ClockAlarm.json property)
+        """
+        data = json.loads(data)
+        self._time = datetime.time.fromisoformat(data['time'])
+        self._ringing = data['ringing']
+        self._next_ring = None if 'next_ring' not in data else data['next_ring']
+        if self._next_ring:
+            self._next_ring = datetime.datetime.fromisoformat(self._next_ring)
+        self._snooze = data['snooze']
+        return self
+
+    def get_time(self, tz:datetime.tzinfo=utctz):
+        """ @return The tz aware alarm ringing datetime.time """
+        return self._get_next_ring().astimezone(tz=tz).timetz()
+
+    def set_time(self, ringtime:datetime.time, tz:datetime.tzinfo=utctz) -> None:
+        """ Set the ringtime
+            @param ringtime : non-tz aware datetime.time
+            @param tz : the given ringtime timezone
+        """
+        ringtime_dt = self.get_next_gte_datetime(ringtime, tz)
+        self._time = ringtime_dt.astimezone(tz=utctz).timetz()
+        if self.is_on:
+            self.__set_next_ring()
+
+    def set_state(self, on:bool) -> None:
+        """ Set the ON/OFF state
+            @param on : if True the alarm will ring at configured time
+        """
+        if on:
+            self.__set_next_ring()
+        else:
+            self._next_ring = None
+            self._ringing = False
+            self._snooze = False
+
+    def snooze(self, minutes:int=15) -> bool:
+        """ Stop ringing alarm for specified amount of minutes
+            @param minutes : amount of time after wich the alarm should ring again
+            @return False if alarm was not ringing else True
+        """
+        if not self._ringing:
+            return False
+        self._next_ring = self.__utcnow() + datetime.timedelta(minutes=minutes)
+        self._ringing = False
+        self._snooze = True
+        return True
+
+    def is_ringing(self) -> bool:
+        """ Check if an alarm should be ringing
+            @return True if the alarm is ringing else False
+        """
+        if not self.is_on:
+            return False
+        if self._ringing:
+            return True
+        utcnow = self.__utcnow()
+        if self._next_ring < utcnow:
+            self._ringing = True
+            self._snooze = False
+            self.__set_next_ring()
+
+        return self._ringing
+
+    def is_snooze(self) -> bool:
+        """ @return True if an alarm is snoozing (ringing again in a specified
+                amount of time after a ClockAlarm.snooze() call)
+        """
+        return self._snooze
+
+    def _get_next_ring(self) -> datetime.datetime:
+        """ @return The next ringing time in utc """
+        return self.get_next_gte_datetime(self._time)
+
+    def __set_next_ring(self) -> None:
+        """ Set the next ring time of the alarm """
+        self._next_ring=self._get_next_ring()
+
+
+    @staticmethod
+    def get_next_gte_datetime(wanted:datetime.time,
+            tz:datetime.tzinfo=utctz) -> datetime.datetime:
+        """ Return the next datetime with a specific time
+            @param wanted : the wanted time, timezone info will be dropped
+            @param tz : the wanted datetime timezone
+            @return The next datetime > now with wanted time
+        """
+        tznow_orig = datetime.datetime.now(tz=tz).replace(microsecond=0)
+        tznow = tznow_orig.replace(hour=tznow_orig.hour)
+        while True:
+            wanted_dt = tznow.replace(hour=wanted.hour,
+                                      minute=wanted.minute,
+                                      second=wanted.second)
+            if wanted_dt > tznow_orig:
+                break
+            tznow += datetime.timedelta(days=1)
+        return wanted_dt

pyws_clock/command.py

@@ -0,0 +1,112 @@
+import shlex
+from argparse import Namespace
+from typing import Callable
+
+from .clock import Clock
+from .errors import DuplicatedCommandError, ArgumentParserError
+from .parser import CommandParser
+
+class Command(object):
+
+    _commands = dict()
+
+    def __init__(self, name:str, run_fun:Callable[[Clock, Namespace], str],
+                 **argument_parser_kwargs:dict):
+        """ Register a new command
+            @param name : The command
+            @param run_fun : The callable handling the command (taking two
+                             arguments, the Clock instance and parsed args)
+            @throws DuplicatedCommandError on duplicated name
+        """
+        if name in self.__class__._commands:
+            msg = 'A command named %r allready exists' % name
+            raise DuplicatedCommandError(msg)
+
+        self.__name = name
+        self.__parser = CommandParser(prog=name, **argument_parser_kwargs)
+        self.__run = run_fun
+
+        self.__class__._commands[self.__name] = self
+
+    @property
+    def name(self) -> str:
+        """ The command name """
+        return self.__name
+
+    @property
+    def description(self) -> str:
+        """ The command description """
+        return self.__parser.description
+
+    @property
+    def usage(self) -> str:
+        """ The command usage """
+        return self.__parser.format_usage().strip()
+
+    @property
+    def help(self) -> str:
+        """ The command help text """
+        return self.__parser.format_help()
+
+    @staticmethod
+    def fmt_ok(message:str='') -> str:
+        """ Format a success command result message """
+        return 'OK:%s' % message
+
+    @staticmethod
+    def fmt_err(reason:str) -> str:
+        """ Format an error command result message """
+        return 'ERR:%s' % reason
+
+    @classmethod
+    def list(cls) -> list[str]:
+        """ Return the list of all command names """
+        return list(cls._commands.keys())
+
+    @classmethod
+    def all(cls) -> dict:
+        """ Return a dict associating command name and Command instance """
+        return {k:v for k,v in cls._commands.items()}
+
+    @classmethod
+    def run_command(cls, clock:Clock, command:str) -> str:
+        """ Run a command on the given Clock instance
+            @param clock : The Clock instance
+            @param command : A string with the command name and its arguments
+        """
+        try:
+            argv = shlex.split(command)
+        except ValueError as expt:
+            return cls.fmt_err(expt)
+
+        if len(argv) == 0:
+            return cls.fmt_err('Empty command')
+
+        if argv[0] not in cls._commands:
+            return cls.fmt_err('Unknown command %r' % argv[0])
+
+        return cls._commands[argv[0]]._run(clock, argv)
+
+    def add_argument(self, name:str, *args, **kwargs):
+        """ Add an argument to the CommandParser instance.
+
+            Same signature than argparse.ArgumentParser.add_argument()
+        """
+        return self.__parser.add_argument(name, *args, **kwargs)
+
+    def add_subparsers(self, *args,**kwargs):
+        """ Add a subparser to the command's ArgumentParser """
+        return self.__parser.add_subparsers(*args, **kwargs)
+
+    def _run(self, clock:Clock, argv:list) -> str:
+        """ Run the command on the given Clock instance
+            @param clock : The Clock instance
+            @param message : The command and its arguments
+            @return Command result as text (formatted by one of the
+                    Command.fmt_ok() or Command.fmt_err() commands)
+        """
+        try:
+            args = self.__parser.parse_args(argv[1:])
+        except ArgumentParserError as expt:
+            return self.fmt_err(expt)
+        return self.__run(clock, args)

pyws_clock/commands.py

@@ -0,0 +1,109 @@
+import argparse
+import datetime
+import json
+
+from .errors import AlarmNameError
+from .clock import Clock
+from .command import Command
+
+
+def tzset_cmd(clk:Clock, args:argparse.Namespace) -> str:
+    """ Function called when "tzset" command received
+        @param clk : the Clock instance
+        @param args : the arguments parsed by argparse
+        @return a well formatted response ready to be sent through the websocket
+    """
+    if clk.set_tz(args.tzname):
+        return Command.fmt_ok()
+    return Command.fmt_err('Invalid timezone %r' % args.tzname)
+
+
+# tzset command declaration
+tzset = Command('tzset', tzset_cmd, description='Set the clock timezone')
+tzset.add_argument('tzname', help='The new timezone (UTC for utc timezone)')
+
+
+def alarm_cmd(clk:Clock, args:argparse.Namespace) -> str:
+    """ Function called when "alarm *" commmand received
+        @param clk : the Clock instance
+        @param args : the arguments parsed by argparse
+        @return a well formatted response ready to be sent through the websocket
+        @throws NotImplementedError if an alarm subcommand was added but not
+                implemented
+    """
+    cmd = args.subcmd
+    ret_details = ''
+    if hasattr(args, 'name') and args.name is not None and cmd != 'add':
+        # try to fetch alarm if needed
+        try:
+            alrm = None if args.name is None else clk.alarm_get(args.name)
+        except AlarmNameError as expt:
+            return Command.fmt_err(expt)
+
+    try:
+        if cmd == 'add':
+            clk.alarm_add(args.name)
+        elif cmd == 'del':
+            clk.alarm_del(args.name)
+        elif cmd == 'list':
+            if args.all:
+                ret = list(clk.alarms.keys())
+            else:
+                ret = clk.alarm_rings()
+
+            alarms = [(name, clk.alarms[name]) for name in ret]
+
+            ret = {name:{'time':alrm.get_time(clk.tz).strftime('%H:%M:%S'),
+                         'on': alrm.is_on,
+                         'ringing': alrm.is_ringing(),
+                         'snooze': alrm.is_snooze()}
+                   for name, alrm in alarms}
+            ret_details = json.dumps(ret)
+        elif cmd == 'snooze':
+            alrm.snooze(args.minutes)
+        elif cmd == 'set':
+            ringtime = datetime.time(args.hour, args.minute, args.second)
+            alrm.set_time(ringtime, clk.tz)
+        elif cmd == 'on':
+            alrm.set_state(True)
+        elif cmd == 'off':
+            alrm.set_state(False)
+        else:
+            raise NotImplementedError('Command %r not implemented' % cmd)
+    except AlarmNameError as expt:
+        return Command.fmt_err(expt)
+
+    return Command.fmt_ok(ret_details)
+
+
+# parser template for alarm name
+_name_parser =  argparse.ArgumentParser(add_help=False)
+_name_parser.add_argument('name', type=str, help='The alarm name')
+
+# alarm command & sub-commands declarations
+alrm = Command('alarm', alarm_cmd, description='Alarm handling')
+
+subalrm = alrm.add_subparsers(required=True, dest='subcmd')
+
+subalrm.add_parser('add', help='Add an alarm', parents=[_name_parser])
+subalrm.add_parser('del', help='Delete an alarm', parents=[_name_parser])
+subalrm.add_parser('on', help='Set an alarm ON', parents=[_name_parser])
+subalrm.add_parser('off', help='Set an alarm OFF', parents=[_name_parser])
+
+alrm_snooze = subalrm.add_parser('snooze', help='Snooze ringing alarms',
+                                 parents=[_name_parser])
+alrm_snooze.add_argument('minutes', nargs='?', default=15, type=float,
+                         help='Ring again after this amount of minutes')
+
+alrm_set = subalrm.add_parser('set', help='Set an alarm ringing time',
+                              parents=[_name_parser])
+alrm_set.add_argument('hour', metavar='HH', type=int, choices=range(24))
+alrm_set.add_argument('minute', metavar='MM', type=int, choices=range(60),
+                      default=0, nargs='?')
+alrm_set.add_argument('second', metavar='SS', type=int, choices=range(60),
+                      default=0, nargs='?')
+
+alrm_list = subalrm.add_parser('list', help='List ringing alarms returning a \
+JSON object')
+alrm_list.add_argument('-a', '--all', action='store_true', default=False,
+                       help='List all alarms')

pyws_clock/config.py

@@ -0,0 +1,43 @@
+import argparse
+import configparser
+
+from .errors import ConfigError
+
+# Config file section
+CONFIG_SECTION = 'pyws_clock'
+# Maps config key name to argparse arg name and type
+CONFIG_ARGS = {
+    'port': ('port', int),
+    'listen': ('listen_address', str),
+    'session_directory': ('session_dir', str),
+    'loglevel': ('verbose', int),
+    'logfile': ('logfile', str),
+}
+
+def parse_config(filename:str, args:argparse.Namespace):
+    """ Updates args parsed by argparse using a configuration file
+        @param filename : configuration file name
+        @param args : Namespace returned by ArgumentParser.parse_args()
+        @return updated Namespace
+        @note args is modified by reference
+    """
+
+    config = configparser.ConfigParser()
+    config.read(filename)
+
+    if CONFIG_SECTION not in config:
+        err = 'There is no section named %r in %r' % (CONFIG_SECTION, filename)
+        raise ConfigError(err)
+
+    err_key = []
+    for key in config[CONFIG_SECTION]:
+        if key not in CONFIG_ARGS:
+            err_key.append(key)
+            continue
+        argname, argtype = CONFIG_ARGS[key]
+        setattr(args, argname, argtype(config[CONFIG_SECTION][key]))
+    if len(err_key) > 0:
+        err = 'Invalid configuration key in %r : %r' % (filename,
+                                                        ','.join(err_key))
+        raise ConfigError(err)
+    return args

pyws_clock/errors.py

@@ -0,0 +1,15 @@
+
+class ConfigError(RuntimeError):
+    pass
+
+class CommandError(ValueError):
+    pass
+
+class ArgumentParserError(CommandError):
+    pass
+
+class DuplicatedCommandError(NameError):
+    pass
+
+class AlarmNameError(ArgumentParserError):
+    pass

pyws_clock/parser.py

@@ -0,0 +1,24 @@
+import argparse
+
+from .errors import ArgumentParserError
+
+class CommandParser(argparse.ArgumentParser):
+    """ ArgumentParser raising exception instead of exiting and printing help
+    """
+
+    def error(self, message):
+        """ Raise an exception instead of printing to stderr and exiting """
+        raise ArgumentParserError(message)
+
+    def exit(self, *args):
+        """ Do not allow a parser to exit the programm """
+        pass
+
+    def print_help(self, *args):
+        """ If print_help() is called raise an exception """
+        raise ArgumentParserError(self.format_usage())
+
+    def add_subparsers(self, *args, **kwargs):
+        """ Create subparsers indicated the good parser class """
+        return super().add_subparsers(*args, **kwargs,
+                                      parser_class=self.__class__)

pyws_clock/server.py

@@ -0,0 +1,67 @@
+import asyncio
+import logging
+import time
+
+import websockets
+from websockets.server import WebSocketServerProtocol
+
+from .clock import Clock
+from .command import Command
+
+logger = logging.getLogger(__name__)
+
+
+async def websocket_handler(sock_cli:WebSocketServerProtocol,
+                            path:str=None) -> None:
+    """ Called for each connecting client
+        @param sock_cli : Client socket
+        @param path : (depends on websockets version?) websocket path
+    """
+    cli_addr = sock_cli.remote_address[0]
+    if 'X-Real-IP' in sock_cli.request_headers:
+        ## TODO add a configuration to indicate expected IP from
+        #  reverse proxy to check if the connection comes from it.
+        cli_addr = sock_cli.request_headers['X-Real-IP']
+    r_addr = '%s(%d)' % (cli_addr,
+                         sock_cli.remote_address[1])
+    logger.info('%s connected' % r_addr)
+
+    # Clock restore/creation given a session_id
+    try:
+        session_id = await sock_cli.recv()
+
+        clock = Clock(session_id=session_id) # per socket Clock  instance
+
+        await sock_cli.send('SESSION:'+clock.session_id)
+
+        last_sent = 0 # last time we sent the hour to the client (timestamp)
+        last_tz = None
+
+
+        while sock_cli.open:
+            # Send date/time + alarms if not sent for more than 1s
+            if time.time() - last_sent >= 1:
+                if last_tz != clock.tzname:
+                    last_tz = clock.tzname
+                    await sock_cli.send('TZN:%s' % last_tz)
+                await sock_cli.send(clock.now().isoformat())
+                last_sent = time.time()
+                for alrm in clock.alarm_rings():
+                    await sock_cli.send('ALRM:%s' % alrm)
+            # Attempt to read message from client
+            tleft = time.time() - last_sent + 1
+            tleft = .01 if tleft < .01 else tleft
+            try:
+                message = await asyncio.wait_for(sock_cli.recv(), tleft)
+                logger.debug('%s << %r' % (r_addr, message))
+                ret = Command.run_command(clock, message)
+                logger.debug('%s >> %r' % (r_addr, ret))
+                await sock_cli.send(ret)
+            except asyncio.TimeoutError:
+                pass # no message in socket
+    except websockets.exceptions.ConnectionClosedOK:
+        logger.info('%s closed connection' %  r_addr)
+    try:
+        del clock
+    except UnboundLocalError:
+        pass

pyws_clock/session.py

@@ -0,0 +1,273 @@
+import logging
+import json
+import os
+import os.path
+import pathlib
+import secrets
+import tempfile
+import time
+import random
+
+from .clock_alarm import ClockAlarm
+
+SESSION_EXPIRE = 3600*24
+MAX_SESSIONS = 0x1000
+
+TOKEN_SZ = 16
+
+logger = logging.getLogger(__name__)
+
+class SessionHandler(object):
+    """ Abstract class for session handler definition """
+
+    def __init__(self, session_id:str):
+        """ Instanciate a new session with a valid session_id """
+        self.__content = dict()
+        self.__session_id = self.validate_session_id(session_id)
+        if self.__class__.__name__ == 'SessionHandler':
+            raise NotImplementedError()
+
+    def tick(self):
+        """ Change expiration time"""
+        raise NotImplementedError()
+
+    def save(self):
+        """ Save the session """
+        return None
+
+    @property
+    def session_id(self) -> str:
+        """ Return the session's ID """
+        return self.__session_id
+
+    @property
+    def content(self) -> dict:
+        """ Return the session's dict """
+        return self.__content # ! no protection against write by reference !
+
+    def __getitem__(self, key:str):
+        """ Allows [] access """
+        return self.__content[key]
+
+    def __setitem__(self, key:str, value:any):
+        """ Allows [] access """
+        self.__content[key] = value
+
+    def __delitem__(self, key:str):
+        """ Delete given item from session """
+        del self.__content[key]
+
+    def __contains__(self, key:str):
+        """ Return true if key is present is session's data """
+        return key in self.__content
+
+    def __iter__(self):
+        """ Iterate over session data keys """
+        return iter(self.__content.keys())
+
+    @classmethod
+    def _purge(cls):
+        """ Purge expired sessions """
+        raise NotImplementedError()
+
+    @classmethod
+    def validate_session_id(cls, session_id:str) -> str:
+        """ If given session_id is valid return it, else return a new valid
+            session id """
+        if not len(session_id) == TOKEN_SZ*2:
+            return cls.new_id()
+        try:
+            int(session_id, 16)
+        except Exception:
+            return cls.new_id()
+        return session_id
+
+    @classmethod
+    def new_id(cls) -> str:
+        """ Return a new session id """
+        return secrets.token_hex(TOKEN_SZ)
+
+
+class RamSession(SessionHandler):
+    """ Session handler storing sessions in memory (all data are lost
+        when the server's process is stopped """
+
+    _sessions = dict()
+    _expires = dict()
+
+    def __init__(self, session_id:str):
+        """ Create/Restor a session """
+        session_id = self.validate_session_id(session_id)
+        if session_id in self.__class__._sessions:
+            logger.info('Restoring session %r' % session_id)
+            content = self.__class__._sessions[session_id]
+        else:
+            session_id = self.new_id()
+            logger.info('New session %r' % session_id)
+            content = dict()
+        super().__init__(session_id)
+
+        for key,val in content.items():
+            self[key] = val
+
+        self.tick()
+        self._purge() # purge after ticking, allowing late session restore
+
+    def tick(self):
+        """ Update session's expiration time """
+        self._expires[self.session_id] = time.time() + SESSION_EXPIRE
+
+    def __del__(self):
+        """ Save session data & update expiration time """
+        self._sessions[self.session_id] = self.content
+        self.tick()
+
+    @classmethod
+    def _purge(cls):
+        """ Delete expired sessions """
+        min_expire = None
+        min_key = None
+        for key in cls._sessions:
+            # Delete expired sessions
+            if key not in cls._expires or cls._expires[key] <= time.time():
+                del cls._sessions[key]
+                if key in cls._expires:
+                    del cls._expires[key]
+            # Looks for older session in case we reached the MAX_SESSIONS count
+            if min_expire is None or cls._expires[key] < min_expire:
+                min_expire = cls._expires[key]
+                min_key = key
+
+        if len(cls._sessions) >= MAX_SESSIONS - 1:
+            if min_key is None:
+                random.choice(list(cls._sessions.keys()))
+            del cls._sessions[min_key]
+            if min_key in self._expires:
+                del cls._expires[min_key]
+
+
+class FileSessionJsonEncoder(json.JSONEncoder):
+    """ Json encoder able to encode ClockAlarm instances """
+
+    def default(self, obj):
+        """ Default encoder """
+        if isinstance(obj, ClockAlarm):
+            return obj.json
+        return json.JSONEncoder.default(self, obj)
+
+class FileSession(SessionHandler):
+    """ Session handler storing sessions into files """
+
+    _session_dir = os.path.join(tempfile.gettempdir(), 'pyws_clock_sessions')
+
+    def __init__(self, session_id:str):
+        """ Create/Restore a session """
+        if not os.path.isdir(self.__class__._session_dir):
+            os.mkdir(self.__class__._session_dir)
+        self._purge()
+
+        session_id = self.validate_session_id(session_id)
+
+        self.__path = pathlib.Path(self.getpath(session_id))
+        if not os.path.isfile(self.path):
+            logger.info('New session %s' % self.path)
+            content = dict()
+            session_id = self.new_id()
+            self.__path = pathlib.Path(self.getpath(session_id))
+            self.path.touch()
+        else:
+            logger.info('Restoring session %s' % self.path)
+            with self.path.open('r') as fp:
+                try:
+                    content = json.load(fp)
+                    content['alarms'] = {k:ClockAlarm()._from_json(v)
+                                         for k,v in content['alarms'].items()}
+                    if not isinstance(content, dict):
+                        raise TypeError('Corrupted session file %s' % self.path)
+                except (TypeError,json.decoder.JSONDecodeError) as expt:
+                    logger.error(expt)
+                    content = dict()
+        super().__init__(session_id)
+
+        for k,v in content.items():
+            self[k] = v
+
+        self.save()
+
+
+    @property
+    def path(self) -> pathlib.Path:
+        """ Return session's file path """
+        return self.__path
+
+    def save(self):
+        """ Save session to disk """
+        with self.path.open('w+') as fp:
+            json.dump(self.content, fp, cls=FileSessionJsonEncoder)
+
+    def __del__(self):
+        """ Save session to disk """
+        logger.debug('Saving session in %s' % self.__path)
+        self.save()
+
+    def tick(self):
+        """ Update file session modification time """
+        self.path.touch()
+
+    @classmethod
+    def _purge(cls):
+        """ Delete expired sessions """
+        min_expire = None
+        min_path = None
+        session_count = 0
+        for fname in os.listdir(cls._session_dir):
+            session_count += 1
+            path = os.path.join(cls._session_dir, fname)
+            mtime = os.path.getmtime(path)
+            if mtime + SESSION_EXPIRE <= time.time():
+                os.remove(path)
+            # Looks for older session in case we reached the MAX_SESSIONS count
+            if min_expire is None or mtime < min_expire:
+                min_expire = mtime
+                min_path = path
+
+        if session_count >= MAX_SESSIONS - 1:
+            if min_path is not None:
+                os.remove(min_path)
+
+    @classmethod
+    def getpath(cls, name:str):
+        """ Given a session id return a file path """
+        return os.path.join(cls._session_dir, name)
+
+    @classmethod
+    def new_id(cls):
+        """ Create a new uniq session id """
+        cls._purge()
+        for _ in range(1024):
+            res = super().new_id()
+            if not os.path.isfile(cls.getpath(res)):
+                return res
+        err = 'Unable to create new session is %r' % cls._session_dir
+        raise RuntimeError(err)
+
+
+class Session(object):
+    """ Wrapper for FileSession and RamSession handlers """
+
+    _handler = RamSession
+
+    def __init__(self):
+        raise NotImplementedError()
+
+    @classmethod
+    def get(cls, session_id:str):
+        """ Create/Restore a session given its ID """
+        return cls._handler(session_id)
+
+    @classmethod
+    def set_file_handler(cls, tempdir:str=None):
+        """ Configure the session handle to FileSession """
+        if tempdir is not None:
+            FileSession._session_dir = tempdir
+        cls._handler = FileSession

requirements.txt

@@ -0,0 +1,2 @@
+python-dateutil==2.8.1
+websockets==8.1

run_server.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+/usr/bin/env python3 -m pyws_clock -C config.ini