CLI: Re-add command line interface (2024) #549

amotl · 2024-10-25T23:01:24Z

About

The CLI interface got lost. This patch intends to bring it back.

Feature: Bring back CLI interface #547

After refactoring, the CLI module is living at responder.ext.cli now.

Setup

From now on, the CLI interface is optional, and its docopt-ng dependency needs to be installed explicitly.

pip install --upgrade 'responder[cli]'

Usage

The feature will also sport a dedicated documentation page now, see preview at Responder CLI.

Software Tests

Previously, the CLI module apparently had no software tests. Now, the two major subcommand operations build vs. run are covered, mostly on their happy paths.

coderabbitai · 2024-10-25T23:01:30Z

Warning

Rate limit exceeded

@amotl has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 7 minutes and 53 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Files that changed from the base of the PR and between d4b7544 and d6133ce.

Walkthrough

The changes in this pull request involve updates to the Responder framework's package configuration, installation instructions, and documentation. Key modifications include the addition of a console script entry point in setup.py, enhancements to the README.md for installation commands, and the introduction of a new CLI section in the documentation. Additionally, several test cases have been added to validate CLI commands, and new utility functions have been introduced for server management and dynamic module loading.

Changes

File	Change Summary
`setup.py`	Added `entry_points` for console script and `extras_require` for `cli`.
`README.md`	Updated installation commands and added a new command for CLI and GraphQL support.
`tests/test_cli.py`	Enhanced with new tests for CLI commands and added a module-level docstring.
`docs/source/cli.rst`	Added detailed instructions for using the Responder CLI, including launching applications and building JavaScript apps.
`docs/source/index.rst`	Introduced a new entry for the CLI guide in the documentation's table of contents.
`examples/helloworld.py`	Added an example HTTP service with a simple asynchronous route handler.
`responder/api.py`	Modified `serve` method to manage logging configuration and simplify `uvicorn.run` invocation.
`responder/util/cmd.py`	Introduced classes `ResponderProgram` and `ResponderServer` for command execution and server management.
`responder/util/python.py`	Added functions for loading targets and modules dynamically.
`tests/util.py`	Introduced utility functions for generating random ports and waiting for server responses.
`.gitignore`	Updated to ignore coverage report files.
`responder/__init__.py`	Added a module-level docstring describing the Responder framework.
`responder/ext/cli.py`	Introduced a new CLI with commands for running the server and building assets.

Possibly related PRs

Chore: Format code using Ruff, and fix linter errors #531: The changes in this PR involve modifications to the setup.py file, specifically related to the extras_require dictionary and the addition of an entry point, which directly relates to the changes made in the main PR that also modifies setup.py for similar purposes.
CI: Run link checker and build documentation as GHA workflow #557: This PR updates the README.md file to enhance installation instructions, which aligns with the main PR's changes to the README.md for installation commands, indicating a focus on improving user guidance for package installation.

Suggested labels

ci and infrastructure

Suggested reviewers

kennethreitz
tabotkevin

Poem

🐇 In the meadow, changes bloom,
Responder's CLI finds its room.
With commands to run and build with glee,
A rabbit hops, "Oh, come see!"
Installation made simple, clear as day,
Let's greet the world, hip-hip-hooray! 🌼

Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media?

❤️ Share

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Generate unit testing code for this file.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
- @coderabbitai generate unit testing code for this file.
- @coderabbitai modularize this function.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read src/utils.ts and generate unit testing code.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
- @coderabbitai help me debug CodeRabbit configuration file.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

@coderabbitai pause to pause the reviews on a PR.
@coderabbitai resume to resume the paused reviews.
@coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
@coderabbitai full review to do a full review from scratch and review all the files again.
@coderabbitai summary to regenerate the summary of the PR.
@coderabbitai resolve resolve all the CodeRabbit review comments.
@coderabbitai configuration to show the current CodeRabbit configuration for the repository.
@coderabbitai help to get help.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

amotl · 2024-10-25T23:02:11Z

setup.py

@@ -20,7 +20,9 @@
 required = [
    "aiofiles",
    "apispec>=1.0.0b1",
+    "asgiref",


What's asgiref for in this context? Can it be removed?

Removed again.

Does anyone know why this would be needed?

amotl · 2024-10-27T10:28:10Z

Hi again. We had to resolve some woes about Windows support and flakyness, mostly revolving around software testing. Now that CI signalled success a few times in a row, we guess the patch is finally ready now.

amotl · 2024-10-27T14:51:32Z

tests/test_cli.py

+def test_cli_run(capfd):
+    """
+    Verify that `responder run` works as expected.
+    """
+
+    # Sanity checks.
+    target = Path("examples") / "helloworld.py"
+    if not target.is_file():
+        raise FileNotFoundError(f"Example file not found: {target}")
+
+    # Invoke `responder run`.
+    # Start a Responder service instance in the background, using its CLI.
+
+    # Make it terminate itself after serving one HTTP request.
+    server = ResponderServer(target=str(target), port=random_port(), limit_max_requests=1)
+    try:
+        # Start server and wait until it responds on TCP.
+        server.start()
+        wait_server_tcp(server.port)
+
+        # Submit a single probing HTTP request that also will terminate the server.
+        response = requests.get(
+            f"http://127.0.0.1:{server.port}{HELLO_ENDPOINT}", timeout=REQUEST_TIMEOUT
+        )
+        assert "hello, world!" == response.text
+    finally:
+        server.join(timeout=SERVER_TIMEOUT)
+
+    # Capture process output.
+    time.sleep(SERVER_IDLE_WAIT)
+    output = capfd.readouterr()
+
+    stdout = output.out.strip()
+    assert f'"GET {HELLO_ENDPOINT} HTTP/1.1" 200 OK' in stdout
+
+    stderr = output.err.strip()
+
+    # Define expected lifecycle messages in order.
+    lifecycle_messages = [
+        # Startup phase
+        "Started server process",
+        "Waiting for application startup",
+        "Application startup complete",
+        "Uvicorn running",
+        # Shutdown phase
+        "Shutting down",
+        "Waiting for application shutdown",
+        "Application shutdown complete",
+        "Finished server process",
+    ]
+
+    # Verify messages appear in expected order.
+    last_pos = -1
+    for msg in lifecycle_messages:
+        pos = stderr.find(msg)
+        assert pos > last_pos, f"Expected '{msg}' to appear after previous message"
+        last_pos = pos


This section might resemble the first actual integration test for Responder, including its CLI interface, end-to-end?

The `debug` argument no longer exists. Let's adjust the `log_level` to `debug` instead.

Install: pip install 'responder[cli]' The CLI is an optional subsystem from now on.

Also, refactor to `responder.ext.cli`.

coderabbitai

Caution

Inline review comments failed to post. This is likely due to GitHub's limits when posting large numbers of comments.

Actionable comments posted: 3

🧹 Outside diff range and nitpick comments (4)

tests/util.py (2)

59-101: Consider adding debug logging for error cases.

While the error handling is robust, adding debug logs for specific error cases would aid in troubleshooting.

Consider this enhancement:

             if error_number in transient_socket_error_numbers():
+                logger.debug(f"Ignoring transient error {error_number} while connecting to {endpoint}")
                 pass

             # Unexpected error.
             else:
+                logger.debug(f"Encountered unexpected error {error_number} while connecting to {endpoint}")
                 raise RuntimeError(
                     f"Unexpected error while connecting to {endpoint}: {error_number}"
                 )

103-135: Consider adding debug logging for consistency with wait_server_tcp.

For consistency with wait_server_tcp, consider adding similar debug logging.

Consider this enhancement:

     url = f"{protocol}://{host}:{port}/"
+    logger.debug(f"Waiting for endpoint: {url}")
     for attempt in range(1, attempts + 1):
         try:
             requests.get(url, timeout=delay / 2)  # Shorter timeout for connection
             break
         except requests.exceptions.RequestException:
+            logger.debug(f"Connection attempt {attempt}/{attempts} failed for {url}")
             if attempt < attempts:  # Don't sleep on last attempt
                 time.sleep(delay)

responder/ext/cli.py (1)

33-46: Consider reorganizing imports for better readability.

The imports could be better organized following the common pattern: standard library, third-party packages, and local imports, each group separated by a blank line.

-import logging
-import platform
-import subprocess
-import sys
-import typing as t
-from pathlib import Path
-
-import docopt
-
-from responder.__version__ import __version__
-from responder.util.python import InvalidTarget, load_target

+import logging
+import platform
+import subprocess
+import sys
+import typing as t
+from pathlib import Path
+
+import docopt
+
+from responder.__version__ import __version__
+from responder.util.python import InvalidTarget, load_target

responder/util/cmd.py (1)

170-198: Consider closing socket explicitly in wait_until_ready.

The socket connection test uses a context manager, but it's good practice to explicitly close the socket to ensure immediate resource release, especially in a loop.

-            try:
-                with socket.create_connection(
-                    ("localhost", self.port), timeout=request_timeout
-                ):
-                    return True
+            sock = None
+            try:
+                sock = socket.create_connection(
+                    ("localhost", self.port), timeout=request_timeout
+                )
+                return True
             except (
                 socket.timeout,
                 ConnectionRefusedError,
                 socket.gaierror,
                 OSError,
             ) as ex:
                 logger.debug(f"Server not ready yet: {ex}")
                 time.sleep(delay)
+            finally:
+                if sock:
+                    sock.close()

🛑 Comments failed to post (3)

tests/util.py (1)
21-34: 🛠️ Refactor suggestion

Consider enhancing error handling for socket operations.

While the implementation is solid, it could benefit from more specific error handling.

Consider this enhancement:
 def random_port() -> int:
     sock = socket.socket()
     try:
         sock.bind(("", 0))
         return sock.getsockname()[1]
+    except socket.error as e:
+        raise RuntimeError(f"Failed to allocate random port: {e}") from e
     finally:
         sock.close()
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
def random_port() -> int:
    """
    Return a random available port by binding to port 0.

    Returns:
        int: An available port number that can be used for testing.
    """
    sock = socket.socket()
    try:
        sock.bind(("", 0))
        return sock.getsockname()[1]
    except socket.error as e:
        raise RuntimeError(f"Failed to allocate random port: {e}") from e
    finally:
        sock.close()
responder/ext/cli.py (1)
106-111: 🛠️ Refactor suggestion

Consider using a custom exception for CLI errors.

Instead of raising a generic ValueError, consider creating a custom exception like CLIError that better represents the domain-specific error condition. This would make it easier to handle CLI-specific errors differently from other value errors.
+class CLIError(Exception):
+    """Raised when CLI encounters an error condition."""
+    pass

-            raise ValueError(
+            raise CLIError(
                 f"{ex}. "
                 "Use either a Python module entrypoint specification, "
                 "a filesystem path, or a remote URL. "
                 "See also https://responder.kennethreitz.org/cli.html."
             ) from ex
Committable suggestion was skipped due to low confidence.
responder/util/cmd.py (1)
25-40: 🛠️ Refactor suggestion

Consider caching the program path.

The path() method searches PATH on every call. Consider caching the result to improve performance.
 class ResponderProgram:
+    _cached_path = None
+
     @staticmethod
     def path():
+        if ResponderProgram._cached_path is not None:
+            return ResponderProgram._cached_path
+
         name = "responder"
         if sys.platform == "win32":
             name = "responder.exe"
         program = shutil.which(name)
         if program is None:
             paths = os.environ.get("PATH", "").split(os.pathsep)
             raise RuntimeError(
                 f"Could not find '{name}' executable in PATH. "
                 f"Please ensure Responder is installed correctly. "
                 f"Searched in: {', '.join(paths)}"
             )
         logger.debug(f"Found responder program: {program}")
+        ResponderProgram._cached_path = program
         return program
Committable suggestion was skipped due to low confidence.

amotl

A few more comments from a self-review.

amotl · 2024-10-31T05:49:36Z

.github/workflows/test.yaml

    - name: Install package and run software tests (Python 3.6)
      if: matrix.python-version == '3.6'
      run: |
-        pip install '.[graphql,develop,test]'
+        pip install '.[cli,graphql,develop,test]'
        poe test

    - name: Install and completely validate package (Python >=3.6)
      if: matrix.python-version != '3.6'
      run: |
-        uv pip install '.[graphql,develop,test]' --system
+        uv pip install '.[cli,graphql,develop,test]' --system
        poe check


Should probably be using the full extra now.

amotl · 2024-10-31T05:50:34Z

responder/__init__.py

+This module exports the core functionality of the Responder framework,
+including the API, Request, Response classes and CLI interface.


No longer true?

Suggested change

This module exports the core functionality of the Responder framework,

including the API, Request, Response classes and CLI interface.

This module exports the core functionality of the Responder framework,

including the API, Request, and Response classes.

amotl · 2024-10-31T05:52:29Z

responder/ext/cli.py

+Commands:
+  run     Start the application server
+  build   Build frontend assets using npm


@kennethreitz: Now after learning it, I think the second subcommand responder build is debatable. Did you keep and/or evolve it within Dyne, @tabotkevin?

amotl · 2024-10-31T05:53:40Z

tests/test_cli.py

+- responder run: Server execution
+
+Requirements:
+- The `docopt` package must be installed


Time flies.

Suggested change

- The `docopt` package must be installed

- The `docopt-ng` package must be installed

amotl commented Oct 25, 2024

View reviewed changes

amotl requested review from kennethreitz and tabotkevin October 25, 2024 23:02

amotl force-pushed the bring-back-cli branch from 14bd489 to 2caf792 Compare October 25, 2024 23:03

amotl changed the title ~~CLI build command~~ CLI build command (2024) Oct 25, 2024

amotl marked this pull request as ready for review October 25, 2024 23:03

amotl mentioned this pull request Oct 25, 2024

Feature: Bring back CLI interface #547

Open