add connection management to the CLI to support testing, debugging, getting started, and infra as code #148
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…feat/cli-enrichment
This commit introduces comprehensive support for managing Hookdeck connections through the CLI. It includes the following key features: - **Full CRUD and Lifecycle Commands:** Implements `connection create`, `list`, `get`, `update`, `delete`, `enable`, `disable`, `pause`, `unpause`, `archive`, and `unarchive`. - **Inline Source Creation with Authentication:** The `connection create` command now supports a full range of source authentication schemes (webhook secret, API key, basic auth, HMAC) via a universal flag set and a flexible JSON fallback. - **Dynamic Type Registry:** A new system dynamically fetches source type definitions and validation rules from the OpenAPI spec, ensuring the CLI stays in sync with the API. - **JSON Output:** Adds a consistent `--output json` flag to the `create`, `list`, `get`, and `update` commands for scriptable, machine-readable output. - **Expanded Acceptance Tests:** The test suite has been significantly updated to provide end-to-end testing for the full connection lifecycle, including all new authentication and output features.
This commit refactors the Unknown command "connection" for "hookdeck". See "hookdeck --help" for a list of available commands. command to use a single, unified API call () when creating a connection with inline sources and destinations. Previously, the command made up to three separate API calls, which was inefficient and did not align with the API's capabilities. The following changes were made: - The function in has been completely refactored to build a single, nested request object. - The API client in and related structs were updated to support the unified request. - Helper functions and were introduced to construct the nested source and destination objects. - The acceptance tests were updated to validate the new, more efficient workflow.
Removes the unused and client files and their corresponding tests. The necessary structs for and have been consolidated into where they are used. Also includes minor fixes to pass the test suite and linter.
This reverts commit 13bc1ab.
…ations - Remove CliPath field from Destination and DestinationCreateRequest structs - Add GetCLIPath() and SetCLIPath() helper methods to access config.path - Update connection_get.go to use GetCLIPath() helper method - Aligns with OpenAPI spec 2025-07-01 where CLI destinations use config.path
- Delete test-scripts/test-acceptance.sh (100% coverage verified) - Update .github/workflows/test-acceptance.yml to run Go tests - Document testing approach in README.md - Add coverage mapping table in test/acceptance/README.md
- Add retry, filter, transform, delay, and deduplicate rules - Support destination rate limiting (per second/minute/hour) - Add comprehensive acceptance tests - Update design documentation
- Implement idempotent upsert command (create or update by name) - Add dry-run support for previewing changes - Remove deprecated update command in favor of upsert - Add 10 comprehensive acceptance tests with input/output validation - Fix API validation for partial updates - Change name from flag to positional argument per design spec - Update documentation and examples All 21 connection tests passing
Planning Documentation Consolidation: - Create connection-management-status.md as single source of truth (98% complete) - Update README.md to reflect current status with commit references - Extract general patterns to AGENTS.md (ordered arrays, idempotent upsert) - Delete 8 obsolete planning documents (completed/superseded) - Update resource-management-implementation.md with connection completion REFERENCE.md Accuracy Updates: - Fix shell completion section (remove unsupported fish/PowerShell) - Update implementation status table (connection management now ✅) - Rewrite Connections section from "Planned" to "Fully Implemented" - Document all 11 connection commands with 40+ flags - Add 9 comprehensive examples covering authentication, rules, rate limiting - Document --output json support (verified in source code) - Update Current Limitations to reflect actual capabilities All documentation now 100% accurate to CLI implementation. Verified against pkg/cmd/ source files and acceptance tests.
Reduced unnecessary duplicate GET requests in connection upsert operations. BEFORE: - Validation phase: 1 GET (check existence for validation logic) - Execution phase: 1 GET (check existence again for request building) - Upsert: 1 PUT Total: 2 GET + 1 PUT = 3 API calls AFTER: - Full upsert (source/dest specified): 1 PUT only (67% reduction) - Partial update (no source/dest): 1 GET + 1 PUT (33% reduction) - Dry-run: 1 GET only (no change, needed for preview) Key Changes: - Removed GET request from validation phase entirely - Made GET request conditional in execution phase - Only fetch existing connection when ACTUALLY needed: 1. Dry-run mode (to show accurate preview) 2. Partial update (API requires source/destination even for updates) - Simplified validation to check only flag consistency - Added helper methods to detect which flags are provided API Behavior Confirmed: The Hookdeck PUT /connections endpoint requires EITHER source_id OR source (and same for destination) in EVERY request. It returns 422 error if both are omitted: "value must contain at least one of [destination_i- Execution phase: 1 GET (c must contain at least one of [source_- Upsert: 1
…or improved idempotency and validation
…ples for inline resource creation, authentication, and lifecycle management
…create command in documentation
…ed OAuth2 flags - Add support for all 8 Hookdeck authentication types: * Hookdeck Signature (default, explicit flag) * Bearer Token * Basic Auth * API Key (header/query) * Custom Signature (HMAC) * OAuth2 Client Credentials * OAuth2 Authorization Code * AWS Signature - Consolidate OAuth2 flags for simpler, consistent naming: * --destination-oauth2-auth-server (shared by both OAuth2 flows) * --destination-oauth2-client-id * --destination-oauth2-client-secret * --destination-oauth2-scopes (comma-separated) * --destination-oauth2-auth-type (Client Credentials only) * --destination-oauth2-refresh-token (Authorization Code only) - Add comprehensive test coverage: * 19 unit tests for auth config builder * 3 new acceptance tests for OAuth2 and AWS authentication * All tests verify auth configuration stored in destination JSON - Update documentation in REFERENCE.md with all auth options - All flags available in both connection create and upsert commands
…ethod fields - Add --destination-path-forwarding-disabled flag (accepts true/false) - Add --destination-http-method flag (accepts GET, POST, PUT, PATCH, DELETE) - Both flags available in connection create and upsert commands - Implement HTTP method validation with clear error messages - Add buildDestinationInputForUpdate() for partial config updates in upsert - Update REFERENCE.md documentation with explicit parameter types - Add comprehensive acceptance tests for create and upsert scenarios - All tests passing (create and upsert functionality validated)
…) to connection create/upsert - Add --source-allowed-http-methods flag (comma-separated: GET,POST,PUT,PATCH,DELETE) - Add --source-custom-response-content-type flag (json, text, xml) - Add --source-custom-response-body flag (max 1000 chars) - Update buildSourceConfig() with validation for new fields - Fix hasAnySourceFlag() to detect all source config flags - Fix needsExisting logic to detect source config-only updates - Add buildSourceInputForUpdate() for proper config merging during upsert - Add 23 unit tests in connection_source_config_test.go - Add 6 acceptance tests covering create and upsert scenarios - Update REFERENCE.md with documentation and examples
…nd enhanced output - Add [BETA] flag to connection command with feedback URL for issue reporting - Add plural aliases: 'connections' and 'projects' for better UX - Enhance connection create/upsert output format: - Show success message with checkmark (✔) - Display connection ID in parentheses after name for consistency - Include source type and URL - Include destination type and type-specific fields (URL for HTTP, Path for CLI) - Remove unnecessary API verification call in connection create for better performance - Update acceptance tests to validate new output format - Clean up verbose logging messages during connection creation
leggetter
changed the title
…29 rate limit errors with exponential back-off during polling - Add SuppressRateLimitErrors flag to Client for configurable error logging - Implement exponential back-off (1s -> 30s max) when polling encounters 429s - Log rate limit events at DEBUG level when suppressed, ERROR otherwise - Fix nil pointer dereference bug when accessing resp.StatusCode on error - Enable rate limit suppression in login polling where 429s are expected - Add isRateLimitError() and calculateBackoff() helper functions
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This pull request introduces comprehensive documentation improvements and workflow updates for the Hookdeck CLI, focusing on connection management features, usage examples, testing instructions, and planning status. It also modernizes the acceptance test workflow to use Go's built-in test runner. These changes make it much easier for users and contributors to understand, use, and test the CLI's connection management capabilities.
Documentation Enhancements
README.mdwith detailed usage examples for all aspects of connection management, including creation, authentication, rules, rate limiting, upsert, listing/filtering, lifecycle management, and deletion. This provides clear, copy-paste-ready CLI commands for common scenarios.README.mdwith instructions for running acceptance tests locally and in CI, including environment setup and links to further documentation..plans/README.mdsummarizing the status, achievements, and development guidelines for connection management, with references to active planning documents and design principles..plans/connection-management/connection-management-status.md, a detailed status and design document outlining completed features, optional enhancements, key design decisions, implementation files, and architectural patterns for connection management.Workflow and Testing Improvements
.github/workflows/test-acceptance.ymlto run acceptance tests usinggo testinstead of a shell script, simplifying CI configuration and aligning with Go best practices.Quick Reference and Usability
README.mdfor quick reference.These changes collectively improve the developer and user experience by making the CLI's capabilities more discoverable, easier to use, and simpler to test.
References: