ciplink-tagserver 0.1.0__py3-none-any.whl

ciplink_tagserver/__init__.py

@@ -0,0 +1,3 @@
+"""One server per site that owns the PLC connections and serves tag values over a WebSocket."""
+
+__version__ = "0.1.0"

ciplink_tagserver/cli.py

@@ -0,0 +1,128 @@
+"""ciplink-tagserver run | dump-tags | types | service"""
+
+import argparse
+import json
+import logging
+import logging.handlers
+from pathlib import Path
+import urllib.parse
+import urllib.request
+
+from .config import load_config
+from .values import type_name
+
+
+def run(args):
+    import uvicorn
+
+    from .server import create_app
+
+    config = load_config(args.config)
+    log_config = None if args.log_file else uvicorn.config.LOGGING_CONFIG  # with a log file, uvicorn logs go there too
+    uvicorn.run(create_app(config, mock=args.mock), host=config.host, port=config.port, log_config=log_config)
+
+
+def service(args):
+    from . import service as svc
+
+    config = Path(args.config).resolve()
+    log_file = Path(args.log_file).resolve() if args.log_file else config.with_name("tagserver.log")
+    if args.action == "install":
+        return svc.install(args.name, config, log_file)
+    if args.action == "remove":
+        return svc.remove(args.name)
+    if args.action == "status":
+        return svc.status(args.name)
+    args.mock, args.config, args.log_file = False, str(config), str(log_file)
+    svc.supervise(lambda: run(args))  # "run": what the installed task executes
+
+
+def setup_logging(log_file=None):
+    handlers = [logging.StreamHandler()]
+    if log_file:
+        handlers = [logging.handlers.RotatingFileHandler(log_file, maxBytes=10_000_000, backupCount=5, encoding="utf-8")]
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s", handlers=handlers)
+
+
+def dump_tags(args):
+    """Uploads the tag list of one PLC (reads only) and writes it in the mock_tags format."""
+    from .server import driver_factory
+
+    config = load_config(args.config)
+    with driver_factory(config.plcs[args.plc]) as plc:
+        tags = {name: type_name(info) for name, info in plc.tags.items()}
+    with open(args.out, "w", encoding="utf-8") as file:
+        json.dump(tags, file, indent=2)
+    print(f"wrote {len(tags)} tags to {args.out}")
+
+
+def fetch_tags(url, token, plc):
+    """GET <url>/tags?plc=NAME; returns the "tags" list."""
+    query = f"/tags?plc={urllib.parse.quote(plc)}" if plc else "/tags"
+    request = urllib.request.Request(url.rstrip("/") + query, headers={"Authorization": f"Bearer {token}"})
+    with urllib.request.urlopen(request) as response:
+        return json.load(response)["tags"]
+
+
+def tag_names(tags):
+    """Readable names: each tag, but for an AOI its readable members (Inst.Member) instead of the instance."""
+    names = []
+    for tag in tags:
+        if "aoi_readable" in tag:
+            names += [f"{tag['name']}.{member}" for member in tag["aoi_readable"]]
+        else:
+            names.append(tag["name"])
+    return names
+
+
+def types(args):
+    """Writes a TypeScript union of the tag names served by a running tag server."""
+    plcs = args.plc or [None]
+    names = []
+    for plc in plcs:
+        prefix = f"{plc}/" if len(plcs) > 1 else ""
+        names += [prefix + name for name in tag_names(fetch_tags(args.url, args.token, plc))]
+    names = list(dict.fromkeys(names))
+    lines = "".join(f"\n  | {json.dumps(name)}" for name in names) or " never"
+    with open(args.out, "w", encoding="utf-8") as file:
+        file.write(f"// Generated by ciplink-tagserver types. Do not edit.\nexport type TagName ={lines};\n")
+    print(f"wrote {len(names)} tag names to {args.out}")
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="ciplink-tagserver")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    p = commands.add_parser("run", help="serve tag values over a WebSocket")
+    p.add_argument("--config", default="tagserver.toml")
+    p.add_argument("--mock", action="store_true", help="serve fake values from each PLC's mock_tags file")
+    p.add_argument("--log-file", help="write logs to this file (rotated at 10 MB, 5 kept) instead of the console")
+    p.set_defaults(func=run)
+
+    p = commands.add_parser("service", help="run at Windows startup (install/remove need an administrator terminal)")
+    p.add_argument("action", choices=["install", "remove", "status", "run"])
+    p.add_argument("--config", default="tagserver.toml")
+    p.add_argument("--name", default="ciplink-tagserver", help="Task Scheduler task name")
+    p.add_argument("--log-file", help="default: tagserver.log next to the config")
+    p.set_defaults(func=service)
+
+    p = commands.add_parser("dump-tags", help="write a PLC's tag list as a mock_tags file")
+    p.add_argument("--config", default="tagserver.toml")
+    p.add_argument("--plc", required=True)
+    p.add_argument("--out", required=True)
+    p.set_defaults(func=dump_tags)
+
+    p = commands.add_parser("types", help="write the tag names of a running server as a TypeScript type")
+    p.add_argument("--url", default="http://127.0.0.1:8765")
+    p.add_argument("--token", required=True)
+    p.add_argument("--plc", action="append", help="repeat for several PLCs; names are then qualified as PLC/tag")
+    p.add_argument("--out", required=True)
+    p.set_defaults(func=types)
+
+    args = parser.parse_args(argv)
+    setup_logging(getattr(args, "log_file", None))
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ciplink_tagserver/config.py

@@ -0,0 +1,76 @@
+"""Reads the TOML config file."""
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class PlcConfig:
+    name: str
+    path: str
+    tag_cache_file: str | None = None
+    mock_tags: str | None = None
+
+
+@dataclass
+class TokenConfig:
+    name: str
+    secret: str
+    write: list[str] = field(default_factory=list)  # fnmatch patterns on qualified names
+
+
+@dataclass
+class Config:
+    host: str = "127.0.0.1"
+    port: int = 8765
+    cycle_ms: int = 250
+    audit_log: str = "audit.log"
+    plcs: dict[str, PlcConfig] = field(default_factory=dict)
+    tokens: dict[str, TokenConfig] = field(default_factory=dict)
+
+    def qualify(self, name: str) -> tuple[str, str]:
+        """Splits ``<plc>/<tag>`` into (plc, tag); an unqualified name means the only PLC, if there is one."""
+        if "/" in name:
+            plc, tag = name.split("/", 1)
+            if plc not in self.plcs:
+                raise ValueError(f"unknown PLC {plc!r}")
+        elif len(self.plcs) == 1:
+            plc, tag = next(iter(self.plcs)), name
+        else:
+            raise ValueError(f"tag {name!r} must be qualified as <plc>/<tag>")
+        if not tag:
+            raise ValueError(f"empty tag name in {name!r}")
+        return plc, tag
+
+
+def load_config(path) -> Config:
+    path = Path(path)
+    with open(path, "rb") as file:
+        return parse_config(tomllib.load(file), path.parent)
+
+
+def parse_config(data: dict, base_dir=".") -> Config:
+    """Builds a Config from the parsed TOML; relative file paths are relative to ``base_dir``."""
+    base = Path(base_dir)
+
+    def resolve(value):
+        return str(base / value) if value else None
+
+    server = data.get("server", {})
+    config = Config(
+        host=server.get("host", "127.0.0.1"),
+        port=server.get("port", 8765),
+        cycle_ms=server.get("cycle_ms", 250),
+        audit_log=resolve(server.get("audit_log", "audit.log")),
+    )
+    for name, plc in data.get("plc", {}).items():
+        config.plcs[name] = PlcConfig(
+            name=name,
+            path=plc["path"],
+            tag_cache_file=resolve(plc.get("tag_cache_file")),
+            mock_tags=resolve(plc.get("mock_tags")),
+        )
+    for name, token in data.get("token", {}).items():
+        config.tokens[name] = TokenConfig(name=name, secret=token["secret"], write=list(token.get("write", [])))
+    return config

ciplink_tagserver/mock.py

@@ -0,0 +1,76 @@
+"""A fake driver for --mock: serves the tags listed in the PLC's ``mock_tags`` JSON file."""
+
+import json
+import random
+
+from ciplink import Tag
+
+INTS = {"SINT", "INT", "DINT", "LINT", "USINT", "UINT", "UDINT", "ULINT"}
+FLOATS = {"REAL", "LREAL"}
+
+
+def initial(data_type):
+    if data_type == "BOOL":
+        return False
+    if data_type in INTS:
+        return 0
+    if data_type in FLOATS:
+        return 0.0
+    if data_type == "STRING":
+        return ""
+    return None
+
+
+class MockDriver:
+    """Same calls as LogixDriver as far as the worker uses them; numbers random-walk, BOOLs toggle."""
+
+    def __init__(self, cfg):
+        types = {}
+        if cfg.mock_tags:
+            with open(cfg.mock_tags, encoding="utf-8") as file:
+                types = json.load(file)
+        self.types = types
+        self.values = {name: initial(data_type) for name, data_type in types.items()}
+        self.data_types = {}
+        self._tag_table_version = 1
+        self._random = random.Random()
+
+    @property
+    def tags(self):
+        return {name: {"tag_name": name, "tag_type": "atomic", "data_type": t, "data_type_name": t}
+                for name, t in self.types.items()}
+
+    def open(self):
+        return True
+
+    def close(self):
+        pass
+
+    def _step(self, name):
+        data_type, value = self.types[name], self.values[name]
+        if data_type == "BOOL":
+            if self._random.random() < 0.1:
+                value = not value
+        elif data_type in INTS:
+            value += self._random.choice((-1, 0, 1))
+        elif data_type in FLOATS:
+            value = round(value + self._random.uniform(-1, 1), 3)
+        self.values[name] = value
+        return value
+
+    def read(self, *tags):
+        results = []
+        for name in tags:
+            if name not in self.types:
+                results.append(Tag(name, None, None, f"Tag doesn't exist - {name}"))
+            elif self.values[name] is None:
+                results.append(Tag(name, None, self.types[name], f"mock does not simulate {self.types[name]}"))
+            else:
+                results.append(Tag(name, self._step(name), self.types[name], None))
+        return results[0] if len(results) == 1 else results
+
+    def write(self, name, value):
+        if name not in self.types:
+            return Tag(name, None, None, f"Tag doesn't exist - {name}")
+        self.values[name] = value
+        return Tag(name, value, self.types[name], None)

ciplink_tagserver/server.py

@@ -0,0 +1,280 @@
+"""The hub (subscriptions, fan-out, writes) and the FastAPI app (WebSocket /ws plus HTTP)."""
+
+import asyncio
+import hmac
+import json
+import logging
+import os
+from collections import Counter
+from contextlib import asynccontextmanager, suppress
+from datetime import datetime, timezone
+from fnmatch import fnmatchcase
+
+from fastapi import FastAPI, HTTPException, Request, WebSocket, WebSocketDisconnect
+
+from .worker import PlcWorker
+
+log = logging.getLogger(__name__)
+
+PROTOCOL = 1
+
+
+def driver_factory(cfg):
+    from ciplink import LogixDriver
+
+    if cfg.tag_cache_file:
+        os.makedirs(os.path.dirname(os.path.abspath(cfg.tag_cache_file)), exist_ok=True)
+        return LogixDriver(cfg.path, tag_cache_file=cfg.tag_cache_file)
+    return LogixDriver(cfg.path)
+
+
+def mock_factory(cfg):
+    from .mock import MockDriver
+
+    return MockDriver(cfg)
+
+
+class Session:
+    def __init__(self, token):
+        self.token = token
+        self.subs = {}  # sub id -> {"tier": int, "tags": {qualified name: name as the client sent it}}
+        self.queue = asyncio.Queue()  # messages to send
+
+    def name_of(self, qname):
+        for sub in self.subs.values():
+            if qname in sub["tags"]:
+                return sub["tags"][qname]
+        return None
+
+
+class Hub:
+    def __init__(self, config, factory):
+        self.config = config
+        self.sessions = set()
+        self.refs = Counter()  # qualified name -> subscriptions across sessions
+        self.loop = None
+        self.workers = {
+            name: PlcWorker(cfg, factory, config.cycle_ms, self._on_values, self._on_status, self._on_meta)
+            for name, cfg in config.plcs.items()
+        }
+
+    def start(self, loop):
+        self.loop = loop
+        for worker in self.workers.values():
+            worker.start()
+
+    def stop(self):
+        for worker in self.workers.values():
+            worker.stop()
+
+    def states(self):
+        return {name: worker.state for name, worker in self.workers.items()}
+
+    def authenticate(self, secret):
+        if not isinstance(secret, str):
+            return None
+        for token in self.config.tokens.values():
+            if hmac.compare_digest(token.secret.encode(), secret.encode()):
+                return token
+        return None
+
+    # worker threads -> event loop
+
+    def _call(self, func, *args):
+        try:
+            self.loop.call_soon_threadsafe(func, *args)
+        except RuntimeError:  # loop closed during shutdown
+            pass
+
+    def _on_values(self, plc, changes):
+        self._call(self._fan_values, plc, changes)
+
+    def _on_status(self, plc, state):
+        self._call(self._broadcast, "status")
+
+    def _on_meta(self, plc):
+        self._call(self._broadcast, "meta", plc)
+
+    def _fan_values(self, plc, changes):
+        for session in self.sessions:
+            d = {}
+            for tag, entry in changes.items():
+                name = session.name_of(f"{plc}/{tag}")
+                if name is not None:
+                    d[name] = entry
+            if d:
+                session.queue.put_nowait({"op": "values", "d": d})
+
+    def _broadcast(self, op, plc=None):
+        message = {"op": "status", "plcs": self.states()} if op == "status" else {"op": "meta", "plc": plc}
+        for session in self.sessions:
+            session.queue.put_nowait(message)
+
+    # requests, on the event loop
+
+    def subscribe(self, session, sub_id, names, tier):
+        """Returns the cached values of the subscribed tags, keyed by the names as given."""
+        if not isinstance(names, list):
+            raise TypeError("tags must be a list")
+        tags = {}
+        for name in names:
+            plc, tag = self.config.qualify(name)
+            tags[f"{plc}/{tag}"] = name
+        if sub_id in session.subs:
+            self.unsubscribe(session, sub_id)
+        session.subs[sub_id] = {"tier": tier, "tags": tags}
+        snapshot = {}
+        for qname, name in tags.items():
+            plc, tag = qname.split("/", 1)
+            self.refs[qname] += 1
+            if self.refs[qname] == 1:
+                self.workers[plc].add_tags([tag])
+            entry = self.workers[plc].snapshot([tag]).get(tag)
+            if entry is not None:
+                snapshot[name] = entry
+        return snapshot
+
+    def unsubscribe(self, session, sub_id):
+        sub = session.subs.pop(sub_id, None)
+        if sub is None:
+            return False
+        for qname in sub["tags"]:
+            self.refs[qname] -= 1
+            if self.refs[qname] <= 0:
+                del self.refs[qname]
+                plc, tag = qname.split("/", 1)
+                self.workers[plc].remove_tags([tag])
+        return True
+
+    def drop(self, session):
+        for sub_id in list(session.subs):
+            self.unsubscribe(session, sub_id)
+        self.sessions.discard(session)
+
+    async def write(self, session, name, value):
+        qname = name
+        try:
+            plc, tag = self.config.qualify(name)
+            qname = f"{plc}/{tag}"
+            if not any(fnmatchcase(qname.lower(), p.lower()) for p in session.token.write):
+                ok, error = False, "not allowed"
+            else:
+                ok, error = await asyncio.wrap_future(self.workers[plc].write(tag, value))
+        except (ValueError, TypeError) as err:
+            ok, error = False, str(err)
+        self.audit(session.token.name, qname, value, ok, error)
+        return ok, error
+
+    def audit(self, token, tag, value, ok, error):
+        line = {"time": datetime.now(timezone.utc).isoformat(), "token": token, "tag": tag,
+                "value": value, "ok": ok, "error": error}
+        with open(self.config.audit_log, "a", encoding="utf-8") as file:
+            file.write(json.dumps(line, default=str) + "\n")
+
+
+def create_app(config, factory=None, mock=False) -> FastAPI:
+    hub = Hub(config, factory or (mock_factory if mock else driver_factory))
+
+    @asynccontextmanager
+    async def lifespan(app):
+        hub.start(asyncio.get_running_loop())
+        yield
+        hub.stop()
+
+    app = FastAPI(title="ciplink-tagserver", lifespan=lifespan)
+    app.state.hub = hub
+
+    @app.get("/health")
+    def health():
+        return {"plcs": {
+            name: {"state": w.state, "last_cycle_ms": w.last_cycle_ms, "last_ok_ts": w.last_ok_ts,
+                   "reconnects": w.reconnects, "reloads": w.reloads}
+            for name, w in hub.workers.items()
+        }}
+
+    @app.get("/stats")
+    def stats():
+        return {
+            "sessions": len(hub.sessions),
+            "plcs": {
+                name: {"reads_per_cycle": w.reads_per_cycle, "last_cycle_ms": w.last_cycle_ms,
+                       "cycle_ms": config.cycle_ms, "overruns": w.overruns, "subscriptions": len(w.tags)}
+                for name, w in hub.workers.items()
+            },
+        }
+
+    @app.get("/tags")
+    def tags(request: Request, plc: str | None = None):
+        auth = request.headers.get("authorization", "")
+        if not auth.startswith("Bearer ") or hub.authenticate(auth[7:]) is None:
+            raise HTTPException(401, "invalid token")
+        if plc is None and len(hub.workers) == 1:
+            plc = next(iter(hub.workers))
+        if plc not in hub.workers:
+            raise HTTPException(404, f"unknown PLC {plc!r}")
+        worker = hub.workers[plc]
+        return {"plc": plc, "state": worker.state, "tags": worker.tag_list}
+
+    @app.websocket("/ws")
+    async def ws_endpoint(ws: WebSocket):
+        await ws.accept()
+        try:
+            hello = await ws.receive_json()
+        except (WebSocketDisconnect, ValueError):
+            hello = None
+        token = None
+        if isinstance(hello, dict) and hello.get("op") == "hello" and hello.get("v") == PROTOCOL:
+            token = hub.authenticate(hello.get("token"))
+        if token is None:
+            with suppress(Exception):
+                await ws.close(4401)
+            return
+
+        session = Session(token)
+        hub.sessions.add(session)
+        await ws.send_json({"op": "welcome", "v": PROTOCOL, "plcs": hub.states(), "write": bool(token.write)})
+
+        async def sender():
+            while True:
+                await ws.send_json(await session.queue.get())
+
+        async def do_write(msg_id, name, value):
+            ok, error = await hub.write(session, name, value)
+            session.queue.put_nowait({"op": "ack", "id": msg_id, "ok": ok, "error": error})
+
+        send_task = asyncio.create_task(sender())
+        write_tasks = set()
+        try:
+            while True:
+                raw = await ws.receive_text()
+                msg_id = None
+                try:
+                    msg = json.loads(raw)
+                    msg_id = msg.get("id")
+                    op = msg["op"]
+                    if op == "sub":
+                        snapshot = hub.subscribe(session, msg["id"], msg["tags"], msg.get("tier", 1))
+                        session.queue.put_nowait({"op": "ack", "id": msg_id, "ok": True, "error": None})
+                        if snapshot:
+                            session.queue.put_nowait({"op": "values", "d": snapshot})
+                    elif op == "unsub":
+                        ok = hub.unsubscribe(session, msg["id"])
+                        session.queue.put_nowait(
+                            {"op": "ack", "id": msg_id, "ok": ok, "error": None if ok else "unknown id"})
+                    elif op == "write":
+                        task = asyncio.create_task(do_write(msg["id"], msg["tag"], msg["value"]))
+                        write_tasks.add(task)
+                        task.add_done_callback(write_tasks.discard)
+                    else:
+                        raise ValueError(f"unknown op {op!r}")
+                except KeyError as err:
+                    session.queue.put_nowait({"op": "error", "id": msg_id, "error": f"missing field {err}"})
+                except (ValueError, TypeError, AttributeError) as err:
+                    session.queue.put_nowait({"op": "error", "id": msg_id, "error": str(err)})
+        except WebSocketDisconnect:
+            pass
+        finally:
+            send_task.cancel()
+            hub.drop(session)
+
+    return app

ciplink_tagserver/service.py

@@ -0,0 +1,99 @@
+"""Runs the tag server at Windows startup as a Task Scheduler task (no extra software needed).
+
+The task runs `ciplink-tagserver service run`, which serves until stopped and starts the server again
+if it ever returns or raises. Installing and removing need an elevated (administrator) terminal.
+"""
+
+import logging
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+from xml.sax.saxutils import escape
+
+log = logging.getLogger(__name__)
+
+RESTART_DELAY = 5  # seconds between a server exit and the next start
+
+TASK_XML = """<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>ciplink-tagserver: serves PLC tag values to React apps</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <BootTrigger><Enabled>true</Enabled></BootTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <UserId>S-1-5-18</UserId>
+      <RunLevel>HighestAvailable</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <RestartOnFailure><Interval>PT1M</Interval><Count>999</Count></RestartOnFailure>
+    <Enabled>true</Enabled>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>{command}</Command>
+      <Arguments>{arguments}</Arguments>
+      <WorkingDirectory>{workdir}</WorkingDirectory>
+    </Exec>
+  </Actions>
+</Task>
+"""
+
+
+def task_xml(config: Path, log_file: Path, python: str = sys.executable) -> str:
+    arguments = f'-m ciplink_tagserver.cli service run --config "{config}" --log-file "{log_file}"'
+    return TASK_XML.format(command=escape(python), arguments=escape(arguments), workdir=escape(str(config.parent)))
+
+
+def schtasks(*args) -> subprocess.CompletedProcess:
+    return subprocess.run(["schtasks", *args], capture_output=True, text=True)
+
+
+def install(name: str, config: Path, log_file: Path) -> int:
+    with tempfile.TemporaryDirectory() as tmp:
+        xml = Path(tmp) / "task.xml"
+        xml.write_text(task_xml(config, log_file), encoding="utf-16")
+        result = schtasks("/Create", "/TN", name, "/XML", str(xml), "/F")
+    if result.returncode != 0:
+        print(result.stderr.strip() or result.stdout.strip())
+        print("Installing needs an administrator terminal: right-click Terminal, 'Run as administrator'.")
+        return result.returncode
+    schtasks("/Run", "/TN", name)
+    print(f"Installed and started task '{name}'. It starts at every boot; logs go to {log_file}")
+    return 0
+
+
+def remove(name: str) -> int:
+    schtasks("/End", "/TN", name)
+    result = schtasks("/Delete", "/TN", name, "/F")
+    print((result.stdout or result.stderr).strip())
+    return result.returncode
+
+
+def status(name: str) -> int:
+    result = schtasks("/Query", "/TN", name, "/V", "/FO", "LIST")
+    print((result.stdout or result.stderr).strip())
+    return result.returncode
+
+
+def supervise(serve, stop=lambda: False, sleep=time.sleep):
+    """Calls serve() again whenever it returns or raises, until stop() is true. Ctrl+C ends it."""
+    while not stop():
+        try:
+            serve()
+            log.warning("tag server stopped, starting it again in %s s", RESTART_DELAY)
+        except KeyboardInterrupt:
+            raise
+        except BaseException as err:  # SystemExit from uvicorn (e.g. port in use) included
+            log.error("tag server failed: %r; starting it again in %s s", err, RESTART_DELAY)
+        sleep(RESTART_DELAY)

ciplink_tagserver/values.py

@@ -0,0 +1,54 @@
+"""Turns driver results into JSON-ready cache entries."""
+
+import math
+
+AOI_LOCAL = "AOI local tag, not externally accessible"
+
+
+def quality(error) -> str:
+    if error is None:
+        return "good"
+    if str(error).startswith("Tag doesn't exist") or AOI_LOCAL in str(error):
+        return "missing"
+    return "bad"
+
+
+def jsonable(value):
+    """Dicts for structs/AOIs, lists for arrays, bytes as hex, non-finite floats as strings."""
+    if isinstance(value, dict):
+        return {str(k): jsonable(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [jsonable(v) for v in value]
+    if isinstance(value, (bytes, bytearray)):
+        return value.hex()
+    if isinstance(value, float) and not math.isfinite(value):
+        return str(value).replace("inf", "Infinity").replace("nan", "NaN")
+    if value is None or isinstance(value, (bool, int, float, str)):
+        return value
+    return str(value)
+
+
+def to_value(tag) -> tuple:
+    """(value, quality) for a driver Tag result; the value is None unless the read succeeded."""
+    q = quality(tag.error)
+    return (jsonable(tag.value) if q == "good" else None), q
+
+
+def type_name(info: dict) -> str:
+    """Data type name of an entry of ``plc.tags``."""
+    if info.get("data_type_name"):
+        return info["data_type_name"]
+    data_type = info.get("data_type")
+    return data_type if isinstance(data_type, str) else (data_type or {}).get("name", "")
+
+
+def tag_list(plc) -> list[dict]:
+    """Tag names with data type and, for AOIs, the readable members, from ``plc.tags``."""
+    result = []
+    for name, info in plc.tags.items():
+        entry = {"name": name, "type": type_name(info)}
+        data_type = info.get("data_type")
+        if info.get("tag_type") == "struct" and isinstance(data_type, dict) and data_type.get("aoi"):
+            entry["aoi_readable"] = list(data_type["aoi"].get("readable", []))
+        result.append(entry)
+    return result

ciplink_tagserver/worker.py

@@ -0,0 +1,205 @@
+"""One thread per PLC: owns the driver, polls the subscribed tags, runs the queued writes."""
+
+import logging
+import queue
+import threading
+import time
+from concurrent.futures import Future
+
+from .values import tag_list, to_value
+
+log = logging.getLogger(__name__)
+
+
+def now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+class PlcWorker:
+    backoff = (1, 2, 5, 10)  # seconds between reconnect attempts, the last one repeats
+    missing_retry = 10  # seconds before a tag the PLC doesn't have is asked for again, unless the tag table reloads
+
+    def __init__(self, cfg, factory, cycle_ms, on_values=None, on_status=None, on_meta=None):
+        self.name = cfg.name
+        self.cfg = cfg
+        self.factory = factory  # cfg -> driver, not yet opened
+        self.cycle = cycle_ms / 1000
+        self.on_values = on_values or (lambda plc, changes: None)  # called from this thread
+        self.on_status = on_status or (lambda plc, state: None)
+        self.on_meta = on_meta or (lambda plc: None)
+
+        self.state = "connecting"
+        self.lock = threading.Lock()  # guards tags and cache
+        self.tags = set()  # tag names polled each cycle
+        self.cache = {}  # tag -> [value, quality, t]
+        self.missing = {}  # tag -> monotonic time to ask for it again; skipped until then
+        self.writes = queue.Queue()  # (tag, value, Future)
+        self.tag_list = []  # for GET /tags, rebuilt here after a connect or reload
+
+        self.last_cycle_ms = None
+        self.last_ok_ts = None
+        self.reads_per_cycle = 0
+        self.overruns = 0
+        self.reconnects = 0
+        self.reloads = 0
+        self._version = None
+
+        self._stop = threading.Event()
+        self.wait = self._stop.wait  # returns True once stopped; tests swap it for a fake clock
+        self._thread = threading.Thread(target=self.run, name=f"plc-{self.name}", daemon=True)
+
+    # called from other threads
+
+    def start(self):
+        self._thread.start()
+
+    def stop(self, timeout=5):
+        self._stop.set()
+        if self._thread.is_alive():
+            self._thread.join(timeout)
+
+    def add_tags(self, tags):
+        with self.lock:
+            self.tags.update(tags)
+
+    def remove_tags(self, tags):
+        with self.lock:
+            for tag in tags:
+                self.tags.discard(tag)
+                self.cache.pop(tag, None)
+                self.missing.pop(tag, None)
+
+    def snapshot(self, tags) -> dict:
+        with self.lock:
+            return {tag: list(self.cache[tag]) for tag in tags if tag in self.cache}
+
+    def write(self, tag, value) -> Future:
+        """Queues a write for the next cycle; the Future gets (ok, error). Never retried."""
+        future = Future()
+        if self.state != "connected":
+            future.set_result((False, "PLC not connected"))
+        else:
+            self.writes.put((tag, value, future))
+        return future
+
+    # the worker thread
+
+    def run(self):
+        attempt = 0
+        while not self._stop.is_set():
+            plc = None
+            try:
+                plc = self.factory(self.cfg)
+                plc.open()
+                self._fail_writes("PLC disconnected")  # any left over from before the connect
+                self._check_version(plc, connecting=True)
+                attempt = 0
+                self._set_state("connected")
+                self._poll(plc)
+            except Exception as err:  # CommError, or anything else the driver raised
+                log.warning("%s: %r", self.name, err)
+            finally:
+                if plc is not None:
+                    try:
+                        plc.close()
+                    except Exception:
+                        pass
+            if self._stop.is_set():
+                break
+            self._fail_writes("PLC disconnected")
+            self._mark_stale()
+            self._set_state("disconnected")
+            delay = self.backoff[min(attempt, len(self.backoff) - 1)]
+            attempt += 1
+            if self.wait(delay):
+                break
+            self.reconnects += 1
+            self._set_state("connecting")
+
+    def _poll(self, plc):
+        while not self._stop.is_set():
+            start = time.monotonic()
+            with self.lock:
+                tags = [tag for tag in self.tags if self.missing.get(tag, 0) <= start]
+            if tags:
+                results = plc.read(*tags)
+                if not isinstance(results, list):
+                    results = [results]
+                t = now_ms()
+                changes = {}
+                with self.lock:
+                    for tag, result in zip(tags, results):
+                        if tag not in self.tags:  # unsubscribed during the read
+                            continue
+                        value, quality = to_value(result)
+                        if quality == "missing":  # don't ask (and make the driver log) every cycle
+                            self.missing[tag] = start + self.missing_retry
+                        else:
+                            self.missing.pop(tag, None)
+                        old = self.cache.get(tag)
+                        if old is None or old[0] != value or old[1] != quality:
+                            self.cache[tag] = [value, quality, t]
+                            changes[tag] = [value, quality, t]
+                if changes:
+                    self.on_values(self.name, changes)
+            self.reads_per_cycle = len(tags)
+            self._check_version(plc)
+            self._run_writes(plc)
+            self.last_ok_ts = now_ms()
+            elapsed = time.monotonic() - start
+            self.last_cycle_ms = round(elapsed * 1000, 1)
+            if elapsed > self.cycle:
+                self.overruns += 1
+            elif self.wait(self.cycle - elapsed):
+                return
+
+    def _run_writes(self, plc):
+        while True:
+            try:
+                tag, value, future = self.writes.get_nowait()
+            except queue.Empty:
+                return
+            try:
+                result = plc.write(tag, value)
+            except Exception as err:
+                future.set_result((False, str(err)))
+                raise
+            future.set_result((result.error is None, result.error))
+
+    def _check_version(self, plc, connecting=False):
+        """Counts a reload and tells the clients when the driver's tag table version changed."""
+        version = getattr(plc, "_tag_table_version", None)
+        changed = version != self._version
+        if changed and self._version is not None:
+            self.reloads += 1
+            log.info("%s: tag table reloaded (version %s -> %s)", self.name, self._version, version)
+            self.on_meta(self.name)
+        self._version = version
+        if changed or connecting:
+            self.tag_list = tag_list(plc)
+            with self.lock:
+                self.missing.clear()  # a new or renamed tag may exist now
+
+    def _fail_writes(self, error):
+        while True:
+            try:
+                _, _, future = self.writes.get_nowait()
+            except queue.Empty:
+                return
+            future.set_result((False, error))
+
+    def _mark_stale(self):
+        changes = {}
+        with self.lock:
+            for tag, entry in self.cache.items():
+                if entry[1] != "stale":
+                    entry[1] = "stale"
+                    changes[tag] = list(entry)
+        if changes:
+            self.on_values(self.name, changes)
+
+    def _set_state(self, state):
+        if state != self.state:
+            self.state = state
+            log.info("%s: %s", self.name, state)
+            self.on_status(self.name, state)

ciplink_tagserver-0.1.0.dist-info/METADATA

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: ciplink-tagserver
+Version: 0.1.0
+Summary: One server per site that owns the PLC connections and serves tag values over a WebSocket
+Author-email: Rowan Ramamurthy <rramamurthy@factoryautomation.com>
+License-Expression: MIT
+Project-URL: Source, https://github.com/RowanRama/ciplink-tagserver
+Project-URL: Driver, https://github.com/RowanRama/ciplink
+Project-URL: React client, https://www.npmjs.com/package/@ciplink/react
+Keywords: plc,allen-bradley,logix,ethernet-ip,hmi,websocket,react
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Manufacturing
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Scientific/Engineering :: Human Machine Interfaces
+Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ciplink<0.2,>=0.1
+Requires-Dist: fastapi
+Requires-Dist: uvicorn[standard]
+Dynamic: license-file
+
+# ciplink-tagserver
+
+One server per site that owns all the PLC connections and serves tag values to React (or any) apps
+over a WebSocket. Apps never talk to the PLCs: each PLC gets one connection, one thread and one poll
+loop, however many screens are open.
+
+It is built on [ciplink](https://pypi.org/project/ciplink/), a fork of pycomm3 that reads by instance
+ID and reloads its tag table by itself after online edits.
+
+## Install
+
+```
+pip install ciplink-tagserver
+```
+
+or from a checkout with [uv](https://docs.astral.sh/uv/): `uv sync`, then `uv run ciplink-tagserver ...`.
+
+## Run
+
+```
+ciplink-tagserver run --config tagserver.toml          # real PLCs
+ciplink-tagserver run --config tagserver.toml --mock   # fake values, no PLC needed
+ciplink-tagserver dump-tags --config tagserver.toml --plc PLC1 --out PLC1_tags.json
+ciplink-tagserver types --url http://127.0.0.1:8765 --token T --plc PLC1 --out src/tags.d.ts
+```
+
+`types` asks a running server for its tag list (`GET /tags`) and writes a TypeScript union,
+`export type TagName = "Line1.Speed" | ...;`. AOIs appear as their readable members (`Valve1.Open`),
+never their local tags. Pass `--plc` once per PLC; with more than one, names are qualified (`PLC1/Line1.Speed`).
+
+Add `--log-file tagserver.log` to `run` to log to a file (rotated at 10 MB, 5 kept) instead of the console.
+
+## Run at Windows startup
+
+From an administrator terminal (right-click Terminal, "Run as administrator"):
+
+```
+ciplink-tagserver service install --config C:\TagServer\tagserver.toml
+ciplink-tagserver service status
+ciplink-tagserver service remove
+```
+
+`install` registers a Task Scheduler task that starts at every boot as SYSTEM, without anyone logging in,
+and starts it now. The task runs `ciplink-tagserver service run`, which starts the server again 5 s after
+it stops for any reason; Task Scheduler also restarts the task itself if it fails. Logs go to
+`tagserver.log` next to the config (`--log-file` to change it). Use full paths in the config, or paths
+relative to it; the task runs in the config's folder. `--name` sets the task name (default
+`ciplink-tagserver`), so several servers can run on one PC with different configs and ports.
+
+## Config
+
+```toml
+[server]
+host = "127.0.0.1"      # localhost only by default
+port = 8765
+cycle_ms = 250          # poll period per PLC
+audit_log = "audit.log" # optional, JSON lines of every write attempt
+
+[plc.PLC1]
+path = "192.168.1.10"                    # a ciplink/pycomm3 path, e.g. "10.0.0.5/1/3"
+tag_cache_file = "cache/PLC1.json"   # optional: fast restarts
+mock_tags = "PLC1_tags.json"         # optional: used only with --mock
+
+[token.viewer]
+secret = "change-me-too"                # no write patterns: read-only
+
+[token.hmi1]
+secret = "change-me"
+write = ["PLC1/Line1.*.SpeedSP", "PLC1/Program:Station1.Door*"]
+```
+
+Relative file paths are relative to the config file. A working example is in `examples/`.
+
+**Tag names** are qualified as `<plc>/<tag>`, e.g. `PLC1/Program:Main.Speed` (a slash cannot appear
+in a Logix tag name). With exactly one PLC configured, unqualified names mean that PLC.
+
+**Write patterns** are `fnmatch` patterns matched against the qualified name, ignoring case. `*` also
+matches dots, and `[...]` is a character class, so to allow `Arr[3]` write `Arr[[]3]` or `Arr?3?`.
+
+## Protocol (v1)
+
+JSON messages over `ws://host:port/ws`.
+
+Client to server:
+
+| message | meaning |
+|---|---|
+| `{"op":"hello","v":1,"token":"<secret>"}` | must be the first message |
+| `{"op":"sub","id":N,"tags":["..."],"tier":1}` | subscribe; reusing an id replaces that subscription |
+| `{"op":"unsub","id":N}` | drop subscription N |
+| `{"op":"write","id":N,"tag":"...","value":...}` | write one tag |
+
+Server to client:
+
+| message | when |
+|---|---|
+| `{"op":"welcome","v":1,"plcs":{"PLC1":"connected"},"write":true}` | after a good hello; `write` says whether the token has any write patterns |
+| `{"op":"values","d":{"<tag>":[value, quality, t]}}` | changed values only; right after a `sub`, the values already cached |
+| `{"op":"ack","id":N,"ok":true,"error":null}` | for `sub`, `unsub` and `write` |
+| `{"op":"status","plcs":{"PLC1":"disconnected"}}` | a PLC changed state |
+| `{"op":"meta","plc":"PLC1"}` | the PLC's tag table was reloaded (online edit, download): fetch `/tags` again |
+| `{"op":"error","id":N,"error":"..."}` | bad request (`id` is null when unknown) |
+
+- A bad token, a first message that is not `hello`, or another protocol version: the socket is closed with code **4401**.
+- Tags in `values` are keyed by the name as the client subscribed it.
+- `quality` is `good`, `bad` (the read failed), `missing` (no such tag, or an AOI local tag that cannot
+  be read from outside) or `stale` (PLC disconnected: the last value is kept). `value` is null for bad and missing.
+- `t` is the time of the change in ms since the epoch.
+- Values: structs and AOIs are objects, arrays are lists, bytes are hex strings, NaN and infinities are
+  the strings `"NaN"`, `"Infinity"`, `"-Infinity"`.
+- PLC states: `connecting`, `connected`, `disconnected`. Reconnects back off 1, 2, 5, then every 10 s.
+- `tier` is stored but not used yet: every subscribed tag is read every cycle.
+- Writes go to the PLC's thread, run after that cycle's read, and the ack carries the driver's result.
+  They are never retried; a write while the PLC is not connected fails at once.
+
+## HTTP
+
+- `GET /health`: per PLC `state`, `last_cycle_ms`, `last_ok_ts`, `reconnects`, `reloads`.
+- `GET /stats`: `sessions`, and per PLC `reads_per_cycle`, `last_cycle_ms`, `cycle_ms`, `overruns`, `subscriptions`.
+- `GET /tags?plc=NAME` with `Authorization: Bearer <secret>`: the PLC's tags with data type and, for
+  AOIs, `aoi_readable` (the members that can be read). `plc` may be left out with one PLC.
+
+## React
+
+[`@ciplink/react`](client/) (in `client/`) is the React side: one provider that owns the WebSocket, and
+hooks and components that subscribe while mounted.
+
+```tsx
+import { TagServerProvider, TagValue, TagLamp, useWriteTag, useTagServer } from "@ciplink/react";
+
+<TagServerProvider url="ws://127.0.0.1:8765/ws" token="change-me">
+  <TagValue name="Line1.Station1.Speed" decimals={1} unit="m/min" />
+  <TagLamp name="Line1.Running" />
+</TagServerProvider>
+```
+
+- `useTag(name)` gives `{value, quality, t}` and re-renders only when that tag changes; subscriptions are
+  counted across components and batched.
+- `useTags(names)`, `useWriteTag(name)` (resolves with the write's ack), `useTagServer()` (connection
+  state, PLC states, `canWrite`).
+- `<TagValue>` and `<TagLamp>` are fixed width with a quality marker, so nothing moves as values change.
+- `<TagLink to as?>` prefetches the tags of a page registered with `registerPage(path, tags)`.
+- Reconnects after 1, 2, 5, then every 10 s, re-subscribes, and shows values as `stale` meanwhile.
+
+A runnable app is in [`examples/react-app/`](examples/react-app/): start the server with
+`uv run ciplink-tagserver run --config examples/tagserver.toml --mock`, build `client/` once
+(`npm install && npm run build`), then `npm install && npm run dev` in the example.
+
+## Mock mode
+
+`--mock` replaces every PLC driver with a fake serving the tags in that PLC's `mock_tags` file:
+
+```json
+{"Line1.Station1.Speed": "REAL", "Line1.Running": "BOOL", "PartCount": "DINT"}
+```
+
+Numbers random-walk, BOOLs toggle now and then, writes are stored, unknown names are `missing`. Other
+types (UDTs, AOIs) read as `bad`; list their atomic members by full name to simulate them.
+`dump-tags` writes this file from a real PLC (it only uploads the tag list), so a mock can mirror it.
+
+## Safety
+
+- Writes are off unless a token has `write` patterns, and only names matching them can be written.
+- Every write attempt, allowed or not, is appended to the audit log.
+- The server binds to `127.0.0.1` by default. Put it behind a TLS proxy before opening it to a network:
+  tokens travel in clear text over plain `ws://` and `http://`.
+- Change the example secrets.

ciplink_tagserver-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+ciplink_tagserver/__init__.py,sha256=9pt2yaFG4fA6D-2teY8riih2HmkycSzQ0SWomRFAS38,119
+ciplink_tagserver/cli.py,sha256=e1j0uzm4oUfz_J1jyyYUhh62aek6nBUQtwpsHCLnCJo,5216
+ciplink_tagserver/config.py,sha256=j1Kyym_3iLuy7-xvQ_E6E5Ul_6_ETPbeGuE2NHWV4Pk,2386
+ciplink_tagserver/mock.py,sha256=GGLf_YWBjhTOgVoGaxJ3wfeL4rfrxw0XSZxNQbaVgbw,2447
+ciplink_tagserver/server.py,sha256=mHACflLR5KTRKtjoiBNJby8XrCl3hMnLODc8X1Nv8Ek,10163
+ciplink_tagserver/service.py,sha256=qyAs7x2zWK3HW6dAsQHZkySWiEUO71jCVKUbDl9otsY,3727
+ciplink_tagserver/values.py,sha256=7ax9kvGsHnS1uBWaR1dWseZoR-g_F1IlJpotl0F9tSQ,1954
+ciplink_tagserver/worker.py,sha256=X6AZwmTp_hFfhXAJXyx8UIS6MxGu4TiyuCVq0efcETc,7660
+ciplink_tagserver-0.1.0.dist-info/licenses/LICENSE,sha256=pmQpfOP_f1yO5vIdYN6ZWk8aMO4VokchyjiG2-vyDnY,1073
+ciplink_tagserver-0.1.0.dist-info/METADATA,sha256=jLSZWvnYCwU2wR0_d3ZkfoRyjNLbUlP4cpR4BUmha3Y,9062
+ciplink_tagserver-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ciplink_tagserver-0.1.0.dist-info/entry_points.txt,sha256=OcI2xY7Nkl9OKKCLyS_3HYy6EQ3S02-WlXHpnzrHXgU,65
+ciplink_tagserver-0.1.0.dist-info/top_level.txt,sha256=IG6yOAQWTOGwoVObfY4yKAMS5oFOke79E8hK4u3t7Nw,18
+ciplink_tagserver-0.1.0.dist-info/RECORD,,

ciplink_tagserver-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ciplink_tagserver-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ciplink-tagserver = ciplink_tagserver.cli:main

ciplink_tagserver-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rowan Ramamurthy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ciplink_tagserver-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ciplink_tagserver