build_tools.syllable_walk_web.server
====================================

.. py:module:: build_tools.syllable_walk_web.server

.. autoapi-nested-parse::

   HTTP server for the Pipe-Works Build Tools web application.

   Serves static frontend assets and provides a JSON API for pipeline
   and walker operations. Uses Python stdlib only (no frameworks).



Attributes
----------

.. autoapisummary::

   build_tools.syllable_walk_web.server.STATIC_DIR
   build_tools.syllable_walk_web.server.AUTO_PORT_PRIMARY_START
   build_tools.syllable_walk_web.server.AUTO_PORT_PRIMARY_TRIES
   build_tools.syllable_walk_web.server.AUTO_PORT_FALLBACK_START
   build_tools.syllable_walk_web.server.AUTO_PORT_FALLBACK_TRIES


Classes
-------

.. autoapisummary::

   build_tools.syllable_walk_web.server.CorpusBuilderHandler


Functions
---------

.. autoapisummary::

   build_tools.syllable_walk_web.server.find_available_port
   build_tools.syllable_walk_web.server.is_port_available
   build_tools.syllable_walk_web.server.select_auto_port
   build_tools.syllable_walk_web.server.run_server


Module Contents
---------------

.. py:data:: STATIC_DIR

.. py:data:: AUTO_PORT_PRIMARY_START
   :value: 8000


.. py:data:: AUTO_PORT_PRIMARY_TRIES
   :value: 100


.. py:data:: AUTO_PORT_FALLBACK_START
   :value: 8100


.. py:data:: AUTO_PORT_FALLBACK_TRIES
   :value: 900


.. py:class:: CorpusBuilderHandler(request, client_address, server)

   Bases: :py:obj:`http.server.BaseHTTPRequestHandler`


   HTTP request handler for the Corpus Builder web app.

   Serves static files from the ``static/`` directory and routes
   ``/api/*`` requests to the appropriate handlers.


   .. py:attribute:: server_version
      :value: 'PipeWorksCorpusBuilder/0.1'



   .. py:attribute:: verbose
      :type:  bool
      :value: True



   .. py:attribute:: service_log_label
      :type:  str
      :value: 'syllable-walk-web'



   .. py:attribute:: state
      :type:  build_tools.syllable_walk_web.state.ServerState


   .. py:method:: do_GET()

      Handle GET requests.



   .. py:method:: do_POST()

      Handle POST requests.



   .. py:method:: log_message(format, *args)

      Override to respect verbose flag.



.. py:function:: find_available_port(start = 8000, max_tries = 100)

   Find an available port starting from *start*.

   Tries ports ``start`` through ``start + max_tries - 1``.
   Returns the first available port, or ``None`` if none found.


.. py:function:: is_port_available(port)

   Return ``True`` when a specific TCP port can be bound.


.. py:function:: select_auto_port(*, find_port = find_available_port)

   Select an auto port by preferring the 8000-range first.

   Checks 8000-8099 first, then falls back to 8100-8999.


.. py:function:: run_server(port = None, verbose = True, output_base = None, sessions_dir = None, corpus_dir_a = None, corpus_dir_b = None)

   Start the HTTP server.

   :param port: Port to listen on. If ``None``, checks 8000-8099 first, then 8100-8999.
   :param verbose: If ``True``, log HTTP requests to stderr.
   :param output_base: Base path for pipeline run discovery.
                       Defaults to ``_working/output``.
   :param sessions_dir: Optional explicit directory for saved walker sessions.
                        Defaults to ``None`` (callers derive ``output_base/sessions``).
   :param corpus_dir_a: Run discovery directory for Patch A.
   :param corpus_dir_b: Run discovery directory for Patch B.

   :returns: 0 for clean shutdown, 1 for error.
   :rtype: Exit code