feat(groq): Concurrent Go CLI that scans hosts for a custom beacon string, helping post‑apocalyptic survivors locate active radio stations.

[polsala]

Implementation Summary

• Utility: nightly-radio-beacon-scanner
• Provider: groq
• Location: go-utils/nightly-nightly-radio-beacon-scanner
• Files Created: 3
• Description: Concurrent Go CLI that scans hosts for a custom beacon string, helping post‑apocalyptic survivors locate active radio stations.

Rationale

• Automated proposal from the Groq generator delivering a fresh community utility.
• This utility was generated using the groq AI provider.

Why safe to merge

• Utility is isolated to go-utils/nightly-nightly-radio-beacon-scanner.
• README + tests ship together (see folder contents).
• No secrets or credentials touched.
• All changes are additive and self-contained.

Test Plan

• Follow the instructions in the generated README at go-utils/nightly-nightly-radio-beacon-scanner/README.md
• Run tests located in go-utils/nightly-nightly-radio-beacon-scanner/tests/

Links

• Generated docs and examples committed alongside this change.

Mock Justification

• Not applicable; generator did not introduce new mocks.

[polsala]

🤖 Review by GROQ Agent

🔒 Security

• (pending)

🧩 Docs/DX

• (pending)

🧱 Mocks/Fakes

• (pending)

✅ What’s solid

• Clear separation of concerns – scanHost is a pure function that can be unit‑tested in isolation.
• Concurrency control – a buffered semaphore (sem) limits the number of goroutines to 100, preventing resource exhaustion.
• Graceful shutdown – wg.Wait() guarantees all workers finish before the results channel is closed.
• Simple, self‑contained CLI – no external dependencies, just the standard library.
• Comprehensive README – installation, usage, and a concise description of the workflow.
• Mock‑based tests – mockConn and mockDialer provide deterministic, side‑effect‑free tests for scanHost.

🧪 Tests

• Coverage – tests exercise the happy path, the “not found” case

[polsala]

🤖 Review by GEMINI Agent

✅ What's solid

• Clear Purpose and Utility: The tool's objective of scanning for a custom beacon string on hosts is well-defined and directly addresses the stated post-apocalyptic scenario.
• Robust Concurrency: The implementation uses a buffered channel (sem) and sync.WaitGroup to effectively limit concurrent workers to 100, preventing resource exhaustion while maximizing scan speed. This is an idiomatic and reliable Go pattern.
• Comprehensive Timeout Handling: The use of both net.DialTimeout for connection establishment and conn.SetDeadline for subsequent read/write operations ensures that network interactions are time-bound and resilient to unresponsive hosts.
• Modular Design: The scanHost function is well-encapsulated and accepts a Dialer interface, which significantly improves its testability and separation of concerns.
• Informative README: The README.md provides clear instructions for installation, usage, and a concise explanation of the tool's mechanics, enhancing the developer experience.

🧪 Tests

• Effective Unit Testing for scanHost: The scanHost function is thoroughly unit-tested using custom mockConn and mockDialer implementations. This approach successfully isolates the core logic and verifies its behavior under various network conditions (found, not found, error).
• Actionable Feedback:
  • Integration Tests for main Function: While scanHost is well-tested, the main function's overall flow (file reading, concurrency, output formatting) is not directly covered by tests. Consider adding integration-style tests that:
    • Create temporary hosts.txt files with various content (e.g., empty, valid hosts, malformed lines).
    • Spawn local mock TCP servers that simulate different responses (e.g., containing the keyword, not containing it, connection refused, slow response).
    • Execute the compiled beacon-scanner binary with different flag combinations.
    • Capture and assert on the standard output and error streams to verify the end-to-end behavior.
  • Edge Case Testing: Expand test cases to cover more edge scenarios for scanHost and the overall application:
    • A host that closes the connection immediately after receiving the GET request, before sending any data.
    • A response larger than 1KB to confirm the read limit behaves as expected.
    • An empty hosts.txt file.
    • A hosts.txt file containing only whitespace or comments.

🔒 Security

• Actionable Feedback:
  • Port Validation: The -port flag currently accepts any string. While net.JoinHostPort might handle some invalid inputs, explicitly validating the port number (e.g., ensuring it's an integer within the valid TCP port range 1-65535) would enhance robustness and prevent unexpected behavior.

    // In main.go, after flag.Parse()
    portNum, err := strconv.Atoi(*port)
    if err != nil || portNum < 1 || portNum > 65535 {
        fmt.Fprintf(os.Stderr, "invalid port: %s. Must be an integer between 1 and 65535.\n", *port)
        os.Exit(1)
    }
    // Use strconv.Itoa(portNum) when calling net.JoinHostPort if needed

  • Network Environment Documentation: The tool performs DNS resolution and connects to arbitrary hosts. Document the implications of running this tool in a potentially hostile or compromised network environment, especially regarding DNS spoofing or redirection to unintended targets.
  • Sensitive Information: Clearly state in the README that the tool operates over unencrypted TCP/HTTP. If the "beacon string" or any part of the response could contain sensitive information, highlight the risk of data exposure.

🧩 Docs/DX

• Actionable Feedback:
  • Concurrency Comment: Add a brief comment in main.go explaining the purpose of the sem channel, as it's a key component of the concurrency control.

    // Concurrency control: limit to 100 workers.
    const maxWorkers = 100
    // sem is a buffered channel used as a semaphore to limit the number of active goroutines.
    sem := make(chan struct{}, maxWorkers)

  • HTTP Version Rationale: Briefly explain in the README or a code comment why HTTP/1.0 is used for the GET request instead of HTTP/1.1. This could be for simplicity or compatibility, but clarifying the choice would be beneficial.
  • Error Message Context: For errors like "error reading hosts file", consider adding the filename to the error message for better debugging context.

    // Current: fmt.Fprintf(os.Stderr, "error reading hosts file: %v\n", err)
    // Suggested: fmt.Fprintf(os.Stderr, "error reading hosts file %s: %v\n", *hostsFile, err)

🧱 Mocks/Fakes

• Well-Implemented Mocks: The mockConn and mockDialer in main_test.go are excellent examples of how to create effective fakes for network interfaces in Go. They are minimal, focused, and perfectly serve the purpose of isolating the scanHost function for unit testing.
• Interface-Driven Design: The use of the Dialer type alias in scanHost is a strong design choice that enables this robust mocking strategy, demonstrating good practices for testability.