lockss-debugpanel 0.8.2__tar.gz

lockss_debugpanel-0.8.2/CHANGELOG.rst

@@ -0,0 +1,85 @@
+=============
+Release Notes
+=============
+
+-----
+0.8.2
+-----
+
+Released: 2026-02-03
+
+   *  Requires Python 3.9-3.13.
+
+-----
+0.8.1
+-----
+
+Released: 2025-08-13
+
+*  **Bug Fixes**
+
+   *  Fixed bug in the processing of ``--nodes`` and ``--auids`` options.
+
+*  **Version 0.8.1-post1** (released: 2026-02-03)
+
+   *  Requires Python 3.9-3.13.
+
+-----
+0.8.0
+-----
+
+Released: 2025-07-01
+
+*  **Features**
+
+   *  Now using *lockss-pybasic* and *pydantic-argparse* internally.
+
+*  **Changes**
+
+   *  Bare arguments are no longer allowed and treated as node references; all node references must be specified via ``--node/-n`` or ``--nodes/-N`` options.
+
+   *  The ``usage`` command has been removed.
+
+-----
+0.7.0
+-----
+
+Released: 2023-05-02
+
+*  **Features**
+
+   *  CLI improvements.
+
+-----
+0.6.1
+-----
+
+Released: 2023-03-16
+
+*  **Bug Fixes**
+
+   *  Files from ``--auids`` were appended to nodes.
+
+-----
+0.6.0
+-----
+
+Released: 2023-03-15
+
+*  **Features**
+
+   *  Now providing a Python library.
+
+-----
+0.5.0
+-----
+
+Released: 2023-03-10
+
+*  **Features**
+
+   *  Completely refactored to be in the package ``lockss.debugpanel``.
+
+   *  Using Poetry to make uploadable to and installable from PyPI as `lockss-debugpanel <https://pypi.org/project/lockss-debugpanel>`_.
+
+   *  Added the ``verify-files`` command.

lockss_debugpanel-0.8.2/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2000-2025, Board of Trustees of Leland Stanford Jr. University
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+may be used to endorse or promote products derived from this software without
+specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

lockss_debugpanel-0.8.2/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: lockss-debugpanel
+Version: 0.8.2
+Summary: Library and command line tool to interact with the LOCKSS 1.x DebugPanel servlet
+License: BSD-3-Clause
+License-File: LICENSE
+Author: Thib Guicherd-Callin
+Author-email: thib@cs.stanford.edu
+Maintainer: Thib Guicherd-Callin
+Maintainer-email: thib@cs.stanford.edu
+Requires-Python: >=3.9,<3.14
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Framework :: Pydantic :: 2
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Archiving
+Classifier: Topic :: Utilities
+Requires-Dist: lockss-pybasic (>=0.1.0,<0.2.0)
+Requires-Dist: pydantic (>=2.11.0,<3.0.0)
+Requires-Dist: pydantic-argparse (>=0.10.0,<0.11.0)
+Requires-Dist: tabulate (>=0.9.0,<0.10.0)
+Project-URL: Documentation, https://docs.lockss.org/en/latest/software/debugpanel
+Project-URL: Repository, https://github.com/lockss/lockss-debugpanel
+Project-URL: changelog, https://github.com/lockss/lockss-debugpanel/blob/main/CHANGELOG.rst
+Project-URL: issues, https://github.com/lockss/lockss-debugpanel/issues
+Description-Content-Type: text/x-rst
+
+==========
+Debugpanel
+==========
+
+.. |RELEASE| replace:: 0.8.2
+.. |RELEASE_DATE| replace:: 2026-02-03
+.. |DEBUGPANEL| replace:: **Debugpanel**
+
+.. image:: https://assets.lockss.org/images/logos/debugpanel/debugpanel_128x128.png
+   :alt: Debugpanel logo
+   :align: right
+
+|DEBUGPANEL| is a library and command line tool to interact with the LOCKSS 1.x DebugPanel servlet.
+
+:Latest release: |RELEASE| (|RELEASE_DATE|)
+:Documentation: https://docs.lockss.org/en/latest/software/debugpanel
+:Release notes: `CHANGELOG.rst <https://github.com/lockss/lockss-debugpanel/blob/main/CHANGELOG.rst>`_
+:License: `LICENSE <https://github.com/lockss/lockss-debugpanel/blob/main/LICENSE>`_
+:Repository: https://github.com/lockss/lockss-debugpanel
+:Issues: https://github.com/lockss/lockss-debugpanel/issues
+
+----
+
+Quick Start::
+
+   # Requires Python 3.9-3.13
+   python --version
+
+   # Install with pipx
+   pipx install lockss-debugpanel
+
+   # Verify installation and discover all the commands
+   debugpanel --help
+
+   # Reload config on lockss1.example.edu:8081
+   debugpanel reload-config -n lockss1.example.edu:8081
+
+   # Crawl AUIDs from list.txt on lockss1.example.edu:8081 and lockss2.example.edu:8081
+   # ...First alternative: each node gets a -n
+   debugpanel crawl -A list.txt -n lockss1.example.edu:8081 -n lockss2.example.edu:8081
+
+   # ...Second alternative: each -n can have more than argument
+   debugpanel crawl -A list.txt -n lockss1.example.edu:8081 lockss2.example.edu:8081
+

lockss_debugpanel-0.8.2/README.rst

@@ -0,0 +1,43 @@
+==========
+Debugpanel
+==========
+
+.. |RELEASE| replace:: 0.8.2
+.. |RELEASE_DATE| replace:: 2026-02-03
+.. |DEBUGPANEL| replace:: **Debugpanel**
+
+.. image:: https://assets.lockss.org/images/logos/debugpanel/debugpanel_128x128.png
+   :alt: Debugpanel logo
+   :align: right
+
+|DEBUGPANEL| is a library and command line tool to interact with the LOCKSS 1.x DebugPanel servlet.
+
+:Latest release: |RELEASE| (|RELEASE_DATE|)
+:Documentation: https://docs.lockss.org/en/latest/software/debugpanel
+:Release notes: `CHANGELOG.rst <https://github.com/lockss/lockss-debugpanel/blob/main/CHANGELOG.rst>`_
+:License: `LICENSE <https://github.com/lockss/lockss-debugpanel/blob/main/LICENSE>`_
+:Repository: https://github.com/lockss/lockss-debugpanel
+:Issues: https://github.com/lockss/lockss-debugpanel/issues
+
+----
+
+Quick Start::
+
+   # Requires Python 3.9-3.13
+   python --version
+
+   # Install with pipx
+   pipx install lockss-debugpanel
+
+   # Verify installation and discover all the commands
+   debugpanel --help
+
+   # Reload config on lockss1.example.edu:8081
+   debugpanel reload-config -n lockss1.example.edu:8081
+
+   # Crawl AUIDs from list.txt on lockss1.example.edu:8081 and lockss2.example.edu:8081
+   # ...First alternative: each node gets a -n
+   debugpanel crawl -A list.txt -n lockss1.example.edu:8081 -n lockss2.example.edu:8081
+
+   # ...Second alternative: each -n can have more than argument
+   debugpanel crawl -A list.txt -n lockss1.example.edu:8081 lockss2.example.edu:8081

lockss_debugpanel-0.8.2/pyproject.toml

@@ -0,0 +1,82 @@
+# Copyright (c) 2000-2025, Board of Trustees of Leland Stanford Jr. University
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+# this list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+# this list of conditions and the following disclaimer in the documentation
+# and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the copyright holder nor the names of its contributors
+# may be used to endorse or promote products derived from this software without
+# specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+[project]
+name = "lockss-debugpanel"
+version = "0.8.2" # Always change in __init__.py, and at release time in README.rst and CHANGELOG.rst
+description = "Library and command line tool to interact with the LOCKSS 1.x DebugPanel servlet"
+license = { text = "BSD-3-Clause" }
+readme = "README.rst"
+requires-python = ">=3.9,<3.14"
+authors = [
+    { name = "Thib Guicherd-Callin",  email = "thib@cs.stanford.edu" },
+]
+maintainers = [
+    { name = "Thib Guicherd-Callin",  email = "thib@cs.stanford.edu" }
+]
+dependencies = [
+    "lockss-pybasic (>=0.1.0,<0.2.0)",
+    "pydantic (>=2.11.0,<3.0.0)",
+    "pydantic-argparse (>=0.10.0,<0.11.0)",
+    "tabulate (>=0.9.0,<0.10.0)"
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Framework :: Pydantic :: 2",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: System :: Archiving",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+changelog = "https://github.com/lockss/lockss-debugpanel/blob/main/CHANGELOG.rst"
+documentation = "https://docs.lockss.org/en/latest/software/debugpanel"
+issues = "https://github.com/lockss/lockss-debugpanel/issues"
+repository = "https://github.com/lockss/lockss-debugpanel"
+
+[tool.poetry]
+include = [
+    "CHANGELOG.rst",
+    "LICENSE",
+    "README.rst",
+]
+packages = [
+    { include = "lockss", from = "src" }
+]
+
+[tool.poetry.scripts]
+debugpanel = 'lockss.debugpanel.cli:main'
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

lockss_debugpanel-0.8.2/src/lockss/debugpanel/__init__.py

@@ -0,0 +1,361 @@
+#!/usr/bin/env python3
+
+# Copyright (c) 2000-2025, Board of Trustees of Leland Stanford Jr. University
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+# this list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+# this list of conditions and the following disclaimer in the documentation
+# and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the copyright holder nor the names of its contributors
+# may be used to endorse or promote products derived from this software without
+# specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+"""
+Library and command line tool to interact with the LOCKSS 1.x DebugPanel servlet.
+"""
+
+__version__ = '0.8.2'
+
+__copyright__ = '''
+Copyright (c) 2000-2025, Board of Trustees of Leland Stanford Jr. University
+'''.strip()
+
+__license__ = __copyright__ + '\n\n' + '''
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+may be used to endorse or promote products derived from this software without
+specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+'''.strip()
+
+
+from base64 import b64encode
+from urllib.request import Request, urlopen
+from typing import Any, Dict
+
+
+type RequestUrlOpenT = Any
+
+
+DEFAULT_DEPTH = 123
+
+
+class Node(object):
+    """
+    Connector to a LOCKSS 1.x node.
+    """
+
+    DEFAULT_PROTOCOL = 'http'
+
+    def __init__(self, node_reference: str, u: str, p: str) -> None:
+        """
+        Constructs a new ``Node`` instance.
+
+        :param node_reference: A LOCKSS 1.x node reference, typically of the
+                               form ``http://lockss.university.edu:8081``. If
+                               no protocol is specified,
+                               ``Node.DEFAULT_PROTOCOL`` is assumed. If a final
+                               slash is included, it is ignored.
+        :type node_reference: str
+        :param u: The username for the given node's Web user interface.
+        :type u: str
+        :param p: The password for the given node's Web user interface.
+        :type p: str
+        """
+        super().__init__()
+        if '://' not in node_reference:
+            node_reference = f'{Node.DEFAULT_PROTOCOL}://{node_reference}'
+        if node_reference.endswith('/'):
+            node_reference = node_reference[:-1]
+        self._url: str = node_reference
+        self._basic: str = b64encode(f'{u}:{p}'.encode('utf-8')).decode('utf-8')
+
+    def authenticate(self, req: Request) -> None:
+        """
+        Does what is necessary to authenticate with the given ``Request``
+        object.
+
+        :param req: A ``Request`` instance.
+        :type req: Request
+        """
+        req.add_header('Authorization', f'Basic {self._basic}')
+
+    def get_url(self) -> str:
+        """
+        Returns the full URL corresponding to this node (with protocol but no
+        final slash).
+
+        :return: The full URL corresponding to this node.
+        :rtype: str
+        """
+        return self._url
+
+
+def check_substance(node: Node, auid: str) -> RequestUrlOpenT:
+    """
+    Performs the DebugPanel servlet "Check Substance" operation on the given
+    node for the given AUID.
+
+    :param node: A ``Node`` instance.
+    :type node: Node
+    :param auid: An AUID.
+    :type auid: str
+    :return: The result of ``urllib.request.urlopen``.
+    :rtype: RequestUrlOpenT
+    :raises Exception: Whatever ``urllib.request.urlopen`` might raise.
+    """
+    return _auid_action(node, auid, 'Check Substance')
+
+
+def crawl(node: Node, auid: str) -> RequestUrlOpenT:
+    """
+    Performs the DebugPanel servlet "Force Start Crawl" operation on the given
+    node for the given AUID.
+
+    :param node: A ``Node`` instance.
+    :type node: Node
+    :param auid: An AUID.
+    :type auid: str
+    :return: The result of ``urllib.request.urlopen``.
+    :rtype: RequestUrlOpenT
+    :raises Exception: Whatever ``urllib.request.urlopen`` might raise.
+    """
+    return _auid_action(node, auid, 'Force Start Crawl')
+
+
+def crawl_plugins(node: Node) -> RequestUrlOpenT:
+    """
+    Performs the DebugPanel servlet "Crawl Plugins" operation on the given
+    node.
+
+    :param node: A ``Node`` instance.
+    :type node: Node
+    :return: The result of ``urllib.request.urlopen``.
+    :rtype: RequestUrlOpenT
+    :raises Exception: Whatever ``urllib.request.urlopen`` might raise.
+    """
+    return _node_action(node, 'Crawl Plugins')
+
+
+def deep_crawl(node: Node, auid: str, depth: int=DEFAULT_DEPTH) -> RequestUrlOpenT:
+    """
+    Performs the DebugPanel servlet "Force Deep Crawl" operation on the given
+    node for the given AUID, with the given depth (default ``DEFAULT_DEPTH``).
+
+    :param node: A ``Node`` instance.
+    :type node: Node
+    :param auid: An AUID.
+    :type auid: str
+    :param depth: A strictly positive refetch depth.
+    :type auid: int
+    :return: The result of ``urllib.request.urlopen``.
+    :rtype: RequestUrlOpenT
+    :raises ValueError: If depth is negative or zero.
+    :raises Exception: Whatever ``urllib.request.urlopen`` might raise.
+    """
+    if depth < 1:
+        raise ValueError(f'depth must be a strictly positive integer, got {depth}')
+    return _auid_action(node, auid, 'Force Deep Crawl', depth=depth)
+
+
+def disable_indexing(node: Node, auid: str) -> RequestUrlOpenT:
+    """
+    Performs the DebugPanel servlet "Disable Indexing" operation on the given
+    node for the given AUID.
+
+    :param node: A ``Node`` instance.
+    :type node: Node
+    :param auid: An AUID.
+    :type auid: str
+    :return: The result of ``urllib.request.urlopen``.
+    :rtype: RequestUrlOpenT
+    :raises Exception: Whatever ``urllib.request.urlopen`` might raise.
+    """
+    return _auid_action(node, auid, 'Disable Indexing')
+
+
+def node(node_reference: str, u: str, p: str) -> Node:
+    """
+    DEPRECATED: Constructs a new ``Node`` instance (see the ``Node``
+    constructor); THIS FUNCTION WILL BE REMOVED IN VERSION 0.9.0.
+
+    :param node_reference: See the ``Node`` constructor.
+    :type node_reference: str
+    :param u: See the ``Node`` constructor.
+    :type node_reference: str
+    :param p: See the ``Node`` constructor.
+    :type node_reference: str
+    :return: See the ``Node`` constructor.
+    :rtype: Node
+    """
+    return Node(node_reference, u, p)
+
+
+def poll(node: Node, auid: str) -> RequestUrlOpenT:
+    """
+    Performs the DebugPanel servlet "Start V3 Poll" operation on the given
+    node for the given AUID.
+
+    :param node: A ``Node`` instance.
+    :type node: Node
+    :param auid: An AUID.
+    :type auid: str
+    :return: The result of ``urllib.request.urlopen``.
+    :rtype: RequestUrlOpenT
+    :raises Exception: Whatever ``urllib.request.urlopen`` might raise.
+    """
+    return _auid_action(node, auid, 'Start V3 Poll')
+
+
+def reindex_metadata(node: Node, auid: str) -> RequestUrlOpenT:
+    """
+    Performs the DebugPanel servlet "Force Reindex Metadata" operation on the
+    given node for the given AUID.
+
+    :param node: A ``Node`` instance.
+    :type node: Node
+    :param auid: An AUID.
+    :type auid: str
+    :return: The result of ``urllib.request.urlopen``.
+    :rtype: RequestUrlOpenT
+    :raises Exception: Whatever ``urllib.request.urlopen`` might raise.
+    """
+    return _auid_action(node, auid, 'Force Reindex Metadata')
+
+
+def reload_config(node: Node) -> RequestUrlOpenT:
+    """
+    Performs the DebugPanel servlet "Reload Config" operation on the given
+    node.
+
+    :param node: A ``Node`` instance.
+    :type node: Node
+    :return: The result of ``urllib.request.urlopen``.
+    :rtype: RequestUrlOpenT
+    :raises Exception: Whatever ``urllib.request.urlopen`` might raise.
+    """
+    return _node_action(node, 'Reload Config')
+
+
+def validate_files(node: Node, auid: str) -> RequestUrlOpenT:
+    """
+    Performs the DebugPanel servlet "Validate Files" operation on the given
+    node for the given AUID.
+
+    :param node: A ``Node`` instance.
+    :type node: Node
+    :param auid: An AUID.
+    :type auid: str
+    :return: The result of ``urllib.request.urlopen``.
+    :rtype: RequestUrlOpenT
+    :raises Exception: Whatever ``urllib.request.urlopen`` might raise.
+    """
+    return _auid_action(node, auid, 'Validate Files')
+
+
+def _auid_action(node: Node, auid: str, action: str, **kwargs) -> RequestUrlOpenT:
+    """
+    Performs one AUID-centric action.
+
+    :param node: A ``Node`` instance.
+    :type node: Node
+    :param auid: An AUID.
+    :type auid: str
+    :param action: An AUID-oriented DebugPanel servlet action string, e.g.
+                   ``Force Deep Crawl``.
+    :type action: str
+    :param kwargs: Key-value pairs of additional query string arguments.
+    :type kwargs: Dict[str, Any]
+    :return: The result of calling `urllib.request.urlopen`` on an appropriate
+             URL.
+    :rtype: RequestUrlOpenT
+    :raises Exception: Whatever ``urllib.request.urlopen`` might raise.
+    """
+    action_encoded = action.replace(" ", "%20")
+    auid_encoded = auid.replace('%', '%25').replace('|', '%7C').replace('&', '%26').replace('~', '%7E')
+    req = _make_request(node, f'action={action_encoded}&auid={auid_encoded}', **kwargs)
+    return urlopen(req)
+
+
+def _make_request(node: Node, query: str, **kwargs) -> Request:
+    """
+    Constructs and authenticates an HTTP request.
+
+    :param node: A ``Node`` instance.
+    :type node: Node
+    :param query: A primary ampersand-separated query string, e.g.
+                  ``"action=MyAction&auid=MyAuid"``.
+    :type query: str
+    :param kwargs: Key-value pairs of additional query string arguments, e.g.
+                   ``(..., depth=99)`` to add ``"&depth=99"``.
+    :type kwargs: Dict[str, Any]
+    :return: An authenticated ``Request`` instance (before
+             ``urllib.request.urlopen`` is called).
+    :rtype: Request
+    """
+    for key, val in kwargs.items():
+        query = f'{query}&{key}={val}'
+    url = f'{node.get_url()}/DebugPanel?{query}'
+    req: Request = Request(url)
+    node.authenticate(req)
+    return req
+
+
+def _node_action(node: Node, action: str, **kwargs) -> RequestUrlOpenT:
+    """
+    Performs one node-centric action.
+
+    :param node: A ``Node`` instance.
+    :type node: Node
+    :param action: A node-oriented DebugPanel servlet action string, e.g.
+                   ``Reload Config``.
+    :type action: str
+    :param kwargs: Key-value pairs of additional query string arguments, e.g.
+                   ``(..., depth=99)`` to add ``"&depth=99"``.
+    :type kwargs: Dict[str, Any]
+    :return: The result of calling `urllib.request.urlopen`` on an appropriate
+             URL.
+    :rtype: RequestUrlOpenT
+    :raises Exception: Whatever ``urllib.request.urlopen`` might raise.
+    """
+    action_encoded = action.replace(" ", "%20")
+    req = _make_request(node, f'action={action_encoded}', **kwargs)
+    return urlopen(req)

lockss_debugpanel-0.8.2/src/lockss/debugpanel/__main__.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+
+# Copyright (c) 2000-2025, Board of Trustees of Leland Stanford Jr. University
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+# this list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+# this list of conditions and the following disclaimer in the documentation
+# and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the copyright holder nor the names of its contributors
+# may be used to endorse or promote products derived from this software without
+# specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+"""
+Entry point for the ``lockss.debugpanel`` module.
+"""
+
+from .cli import main
+
+main()

lockss_debugpanel-0.8.2/src/lockss/debugpanel/cli.py

@@ -0,0 +1,379 @@
+#!/usr/bin/env python3
+
+# Copyright (c) 2000-2025, Board of Trustees of Leland Stanford Jr. University
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+# this list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+# this list of conditions and the following disclaimer in the documentation
+# and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the copyright holder nor the names of its contributors
+# may be used to endorse or promote products derived from this software without
+# specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+"""
+Command line tool to interact with the LOCKSS 1.x DebugPanel servlet.
+"""
+
+from collections.abc import Callable
+from concurrent.futures import Executor, Future, ProcessPoolExecutor, ThreadPoolExecutor, as_completed
+from enum import Enum
+from getpass import getpass
+from itertools import chain
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from pydantic.v1 import BaseModel, Field, FilePath, root_validator, validator
+from pydantic.v1.types import PositiveInt
+from tabulate import tabulate
+
+from lockss.pybasic.cliutil import BaseCli, StringCommand, at_most_one_from_enum, get_from_enum, COPYRIGHT_DESCRIPTION, LICENSE_DESCRIPTION, VERSION_DESCRIPTION
+from lockss.pybasic.errorutil import InternalError
+from lockss.pybasic.fileutil import file_lines, path
+from lockss.pybasic.outpututil import OutputFormatOptions
+from . import Node, RequestUrlOpenT, check_substance, crawl, crawl_plugins, deep_crawl, disable_indexing, poll, reload_config, reindex_metadata, validate_files, DEFAULT_DEPTH, __copyright__, __license__, __version__
+
+
+class JobPool(Enum):
+    """
+    An enum of job pool types.
+
+    See also ``DEFAULT_POOL_TYPE``.
+    """
+    thread_pool = 'thread-pool'
+    process_pool = 'process-pool'
+
+    @staticmethod
+    def from_option(name: str) -> str:
+        """
+        Given an option name with hyphens, return the enum constant name with
+        underscores.
+
+        :param name: An option name with hyphens.
+        :type name: str
+        :return: The corresponding enum constant name with underscores.
+        :rtype: str
+        """
+        return JobPool(name.replace('-', '_'))
+
+
+DEFAULT_POOL_SIZE: Optional[int] = None
+DEFAULT_POOL_TYPE: JobPool = JobPool.thread_pool
+
+
+class NodesOptions(BaseModel):
+    """
+    The --node/-n, --nodes/-N, --password/-p and --username/-u options.
+    """
+    node: Optional[List[str]] = Field([], aliases=['-n'], description='(nodes) add one or more nodes to the set of nodes to process')
+    nodes: Optional[List[FilePath]] = Field([], aliases=['-N'], description='(nodes) add the nodes listed in one or more files to the set of nodes to process')
+    password: Optional[str] = Field(aliases=['-p'], description='(nodes) UI password; interactive prompt if not specified')
+    username: Optional[str] = Field(aliases=['-u'], description='(nodes) UI username; interactive prompt if not unspecified')
+
+    @validator('nodes', each_item=True, pre=True)
+    def _expand_each_nodes_path(cls, v: Path):
+        return path(v)
+
+    def get_nodes(self):
+        ret = [*self.node, *chain.from_iterable(file_lines(file_path) for file_path in self.nodes)]
+        if len(ret) == 0:
+            raise RuntimeError('empty list of nodes')
+        return ret
+
+
+class AuidsOptions(BaseModel):
+    """
+    The --auid/-a and --auids/-A options.
+    """
+    auid: Optional[List[str]] = Field([], aliases=['-a'], description='(AUIDs) add one or more AUIDs to the set of AUIDs to process')
+    auids: Optional[List[FilePath]] = Field([], aliases=['-A'], description='(AUIDs) add the AUIDs listed in one or more files to the set of AUIDs to process')
+
+    @validator('auids', each_item=True, pre=True)
+    def _expand_each_auids_path(cls, v: Path):
+        return path(v)
+
+    def get_auids(self):
+        ret = [*self.auid, *chain.from_iterable(file_lines(file_path) for file_path in self.auids)]
+        if len(ret) == 0:
+            raise RuntimeError('empty list of AUIDs')
+        return ret
+
+
+class DepthOptions(BaseModel):
+    """
+    The --depth/-d option.
+    """
+    depth: Optional[int] = Field(DEFAULT_DEPTH, aliases=['-d'], description='(deep crawl) set crawl depth')
+
+
+class JobPoolOptions(BaseModel):
+    """
+    The --pool-size, --process-pool and --thread-pool options.
+    """
+    pool_size: Optional[PositiveInt] = Field(description='(job pool) set the job pool size')
+    process_pool: Optional[bool] = Field(False, description='(job pool) use a process pool', enum=JobPool)
+    thread_pool: Optional[bool] = Field(False, description='(job pool) use a thread pool', enum=JobPool)
+
+    @root_validator
+    def _at_most_one_pool_type(cls, values):
+        return at_most_one_from_enum(cls, values, JobPool)
+
+    def get_pool_size(self) -> Optional[int]:
+        return self.pool_size if hasattr(self, 'pool_size') else DEFAULT_POOL_SIZE
+
+    def get_pool_type(self) -> JobPool:
+        return get_from_enum(self, JobPool, DEFAULT_POOL_TYPE)
+
+
+class NodeCommand(OutputFormatOptions, JobPoolOptions, NodesOptions):
+    """
+    A pydantic-argparse command for node commands.
+    """
+    pass
+
+class AuidCommand(NodeCommand, OutputFormatOptions, JobPoolOptions, AuidsOptions, NodesOptions):
+    """
+    A pydantic-argparse command for AUID commands except deep-crawl.
+    """
+    pass
+
+class DeepCrawlCommand(AuidCommand, OutputFormatOptions, JobPoolOptions, DepthOptions, AuidsOptions, NodesOptions):
+    """
+    A pydantic-argparse command for deep-crawl.
+    """
+    pass
+
+
+class DebugPanelCommand(BaseModel):
+    """
+    The pydantic-argparse model for the top-level debugpanel command.
+    """
+    check_substance: Optional[AuidCommand] = Field(description='cause nodes to check the substance of AUs', alias='check-substance')
+    copyright: Optional[StringCommand.type(__copyright__)] = Field(description=COPYRIGHT_DESCRIPTION)
+    cp: Optional[NodeCommand] = Field(description='synonym for: crawl-plugins')
+    cr: Optional[AuidCommand] = Field(description='synonym for: crawl')
+    crawl: Optional[AuidCommand] = Field(description='cause nodes to crawl AUs')
+    crawl_plugins: Optional[NodeCommand] = Field(description='cause nodes to crawl plugins', alias='crawl-plugins')
+    cs: Optional[AuidCommand] = Field(description='synonym for: check-substance')
+    dc: Optional[DeepCrawlCommand] = Field(description='synonym for: deep-crawl')
+    deep_crawl: Optional[DeepCrawlCommand] = Field(description='cause nodes to deeply crawl AUs', alias='deep-crawl')
+    di: Optional[AuidCommand] = Field(description='synonym for: disable-indexing')
+    disable_indexing: Optional[AuidCommand] = Field(description='cause nodes to disable metadata indexing for AUs', alias='disable-indexing')
+    license: Optional[StringCommand.type(__license__)] = Field(description=LICENSE_DESCRIPTION)
+    po: Optional[AuidCommand] = Field(description='synonym for: poll')
+    poll: Optional[AuidCommand] = Field(description='cause nodes to poll AUs')
+    rc: Optional[NodeCommand] = Field(description='synonym for: reload-config')
+    reindex_metadata: Optional[AuidCommand] = Field(description='cause nodes to reindex the metadata of AUs', alias='reindex-metadata')
+    reload_config: Optional[NodeCommand] = Field(description='cause nodes to reload their configuration', alias='reload-config')
+    ri: Optional[AuidCommand] = Field(description='synonym for: reindex-metadata')
+    validate_files: Optional[AuidCommand] = Field(description='cause nodes to validate the files of AUs', alias='validate-files')
+    version: Optional[StringCommand.type(__version__)] = Field(description=VERSION_DESCRIPTION)
+    vf: Optional[AuidCommand] = Field(description='synonym for: validate-files')
+
+
+class DebugPanelCli(BaseCli[DebugPanelCommand]):
+    """
+    The debugpanel command line tool.
+    """
+
+    def __init__(self):
+        """
+        Constructs a new ``DebugPanelCli`` instance.
+        """
+        super().__init__(model=DebugPanelCommand,
+                         prog='debugpanel',
+                         description='Tool to interact with the LOCKSS 1.x DebugPanel servlet')
+        self._auids: Optional[List[str]] = None
+        self._auth: Optional[Any] = None
+        self._executor: Optional[Executor] = None
+        self._nodes: Optional[List[str]] = None
+
+    def _check_substance(self, auid_command: AuidCommand) -> None:
+        self._do_auid_command(auid_command, check_substance)
+
+    def _copyright(self, string_command: StringCommand) -> None:
+        self._do_string_command(string_command)
+
+    def _cp(self, node_command: NodeCommand) -> None:
+        self._crawl_plugins(node_command)
+
+    def _cr(self, auid_command: AuidCommand) -> None:
+        self._crawl(auid_command)
+
+    def _crawl(self, auid_command: AuidCommand) -> None:
+        self._do_auid_command(auid_command, crawl)
+
+    def _crawl_plugins(self, node_command: NodeCommand) -> None:
+        self._do_node_command(node_command, crawl_plugins)
+
+    def _cs(self, auid_command: AuidCommand) -> None:
+        self._check_substance(auid_command)
+
+    def _dc(self, deep_crawl_command: DeepCrawlCommand) -> None:
+        self._deep_crawl(deep_crawl_command)
+
+    def _deep_crawl(self, deep_crawl_command: DeepCrawlCommand) -> None:
+        self._do_auid_command(deep_crawl_command, deep_crawl, depth=deep_crawl_command.depth)
+
+    def _di(self, auid_command: AuidCommand) -> None:
+        self._disable_indexing(auid_command)
+
+    def _disable_indexing(self, auid_command: AuidCommand) -> None:
+        self._do_auid_command(auid_command, disable_indexing)
+
+    def _do_auid_command(self, auid_command: AuidCommand, node_auid_func: Callable[[Node, str], RequestUrlOpenT], **kwargs: Dict[str, Any]) -> None:
+        """
+        Performs one AUID-centric command.
+
+        :param auid_command: An ``AuidCommand`` model.
+        :type auid_command: AuidCommand
+        :param node_auid_func: A function that applies to a ``Node`` and an AUID
+                               and returns what ``urllib.request.urlopen``
+                               returns.
+        :type node_auid_func: ``RequestUrlOpenT``
+        :param kwargs: Keyword arguments (needed for the ``depth`` command).
+        :type kwargs: Dict[str, Any]
+        """
+        self._initialize_auth(auid_command)
+        self._initialize_executor(auid_command)
+        self._nodes = auid_command.get_nodes()
+        self._auids = auid_command.get_auids()
+        node_objects = [Node(node, *self._auth) for node in self._nodes]
+        futures: Dict[Future, Tuple[str, str]] = {self._executor.submit(node_auid_func, node_object, auid, **kwargs): (node, auid) for auid in self._auids for node, node_object in zip(self._nodes, node_objects)}
+        results: Dict[Tuple[str, str], Any] = {}
+        for future in as_completed(futures):
+            node_auid = futures[future]
+            try:
+                resp: RequestUrlOpenT = future.result()
+                status: int = resp.status
+                reason: str = resp.reason
+                results[node_auid] = 'Requested' if status == 200 else reason
+            except Exception as exc:
+                results[node_auid] = exc
+        print(tabulate([[auid, *[results[(node, auid)] for node in self._nodes]] for auid in self._auids],
+                       headers=['AUID', *self._nodes],
+                       tablefmt=auid_command.output_format))
+
+    def _do_node_command(self, node_command: NodeCommand, node_func: Callable[[Node], RequestUrlOpenT], **kwargs: Dict[str, Any]) -> None:
+        """
+        Performs one node-centric command.
+
+        :param node_command: A ``NodeCommand`` model.
+        :type auid_command: NodeCommand
+        :param node_func: A function that applies to a ``Node`` and returns
+                          what ``urllib.request.urlopen`` returns.
+        :type node_auid_func: ``RequestUrlOpenT``
+        :param kwargs: Keyword arguments (not currently needed by any command).
+        :type kwargs: Dict[str, Any]
+        """
+        self._initialize_auth(node_command)
+        self._initialize_executor(node_command)
+        self._nodes = node_command.get_nodes()
+        node_objects = [Node(node, *self._auth) for node in self._nodes]
+        futures: Dict[Future, str] = {self._executor.submit(node_func, node_object, **kwargs): node for node, node_object in zip(self._nodes, node_objects)}
+        results: Dict[str, Any] = {}
+        for future in as_completed(futures):
+            node = futures[future]
+            try:
+                resp: RequestUrlOpenT = future.result()
+                status: int = resp.status
+                reason: str = resp.reason
+                results[node] = 'Requested' if status == 200 else reason
+            except Exception as exc:
+                results[node] = exc
+        print(tabulate([[node, results[node]] for node in self._nodes],
+                       headers=['Node', 'Result'],
+                       tablefmt=node_command.output_format))
+
+    def _do_string_command(self, string_command: StringCommand) -> None:
+        """
+        Performs one string command.
+
+        :param string_command: A ``StringCommand`` model.
+        :type auid_command: StringCommand
+        """
+        string_command()
+
+    def _initialize_auth(self, nodes_options: NodesOptions) -> None:
+        """
+        Computes the ``self._auth`` value, possibly after asking for interactive
+        input.
+
+        :param nodes_options: A ``NodesOptions`` model.
+        :type node_options: ``NodesOptions``
+        """
+        _u = nodes_options.username or input('UI username: ')
+        _p = nodes_options.password or getpass('UI password: ')
+        self._auth = (_u, _p)
+
+    def _initialize_executor(self, job_pool_options: JobPoolOptions) -> None:
+        """
+        Initializes the ``Executor``.
+
+        :param job_pool_options: A ``JobPoolOptions`` model.
+        :type job_pool_options: ``JobPoolOptions``.
+        """
+        if job_pool_options.get_pool_type() == JobPool.thread_pool:
+            self._executor = ThreadPoolExecutor(max_workers=job_pool_options.get_pool_size())
+        elif job_pool_options.get_pool_type() == JobPool.process_pool:
+            self._executor = ProcessPoolExecutor(max_workers=job_pool_options.get_pool_size())
+        else:
+            raise InternalError()
+
+    def _license(self, string_command: StringCommand) -> None:
+        self._do_string_command(string_command)
+
+    def _po(self, auid_command: AuidCommand) -> None:
+        self._poll(auid_command)
+
+    def _poll(self, auid_command: AuidCommand) -> None:
+        self._do_auid_command(auid_command, poll)
+
+    def _rc(self, node_command: NodeCommand):
+        self._reload_config(node_command)
+
+    def _ri(self, auid_command: AuidCommand) -> None:
+        self._reindex_metadata(auid_command)
+
+    def _reindex_metadata(self, auid_command: AuidCommand) -> None:
+        self._do_auid_command(auid_command, reindex_metadata)
+
+    def _reload_config(self, node_command: NodeCommand):
+        self._do_node_command(node_command, reload_config)
+
+    def _validate_files(self, auid_command: AuidCommand) -> None:
+        self._do_auid_command(auid_command, validate_files)
+
+    def _vf(self, auid_command: AuidCommand) -> None:
+        self._validate_files(auid_command)
+
+    def _version(self, string_command: StringCommand) -> None:
+        self._do_string_command(string_command)
+
+
+def main() -> None:
+    """
+    Entry point for the debugpanel command line tool.
+    """
+    DebugPanelCli().run()
+
+
+if __name__ == '__main__':
+    main()