Skip to content

Commit c30a626

Browse files
leggetterleggetter
authored
Merge pull request #148 from hookdeck/feat/cli-enrichment
add connection management to the CLI to support testing, debugging, getting started, and infra as code
2 parents 1e6f26d + 58747d1 commit c30a626

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+12422
-95
lines changed

‎.github/workflows/test-acceptance.yml‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ name: Acceptance Tests
33
on:
44
pull_request:
55
branches:
6+
- next
67
- main
78

89
jobs:
@@ -19,8 +20,5 @@ jobs:
1920
with:
2021
go-version: "1.24.9"
2122

22-
- name: Make script executable
23-
run: chmod +x test-scripts/test-acceptance.sh
24-
25-
- name: Run acceptance tests
26-
run: ./test-scripts/test-acceptance.sh
23+
- name: Run Go Acceptance Tests
24+
run: go test ./test/acceptance/... -v -timeout 10m

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,4 @@ default_cassette.yaml
1313
.vscode/
1414
__debug_bin
1515
node_modules/
16+
.env

‎.plans/README.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Hookdeck CLI Planning Documents
2+
3+
## Connection Management - Production Ready ✅
4+
5+
**Status:** 98% complete and production-ready
6+
7+
See [`connection-management-status.md`](./connection-management/connection-management-status.md) for comprehensive documentation of the completed implementation.
8+
9+
**Key Achievements:**
10+
- ✅ Full CRUD operations (create, list, get, upsert, delete)
11+
- ✅ Complete lifecycle management (enable, disable, pause, unpause, archive, unarchive)
12+
- ✅ Source authentication (96+ types) - [Commit 8acf8d3](https://github.com/hookdeck/hookdeck-cli/commit/8acf8d3)
13+
- ✅ Destination authentication (HTTP, CLI, Mock API) - [Commit 8acf8d3](https://github.com/hookdeck/hookdeck-cli/commit/8acf8d3)
14+
- ✅ All 5 rule types (retry, filter, transform, delay, deduplicate) - [Commit 8acf8d3](https://github.com/hookdeck/hookdeck-cli/commit/8acf8d3)
15+
- ✅ Rate limiting configuration
16+
- ✅ Idempotent upsert with dry-run support - [Commit 8ab6cac](https://github.com/hookdeck/hookdeck-cli/commit/8ab6cac)
17+
18+
**Optional Enhancements (Low Priority - 2% remaining):**
19+
- Bulk operations (enable/disable/delete multiple connections)
20+
- Connection count command
21+
- Connection cloning
22+
23+
## Active Planning Documents
24+
25+
- **[`connection-management-status.md`](./connection-management/connection-management-status.md)** - Current implementation status (98% complete)
26+
- **[`resource-management-implementation.md`](./resource-management-implementation.md)** - Overall resource management plan
27+
28+
## Development Guidelines
29+
30+
All CLI development follows the patterns documented in [`AGENTS.md`](../AGENTS.md):
31+
- OpenAPI to CLI conversion rules
32+
- Flag naming conventions
33+
- Type-driven validation patterns
34+
- Command structure standards
35+
- **Ordered array configurations** - For API arrays with ordering (rules, steps, middleware)
36+
- **Idempotent upsert pattern** - For declarative resource management with `--dry-run` support
37+
38+
Design specifications have been consolidated into `AGENTS.md` as general principles with connection management as concrete examples.

‎.plans/connection-management/connection-management-status.md‎

Lines changed: 314 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,314 @@
1+
# Connection Management Implementation Status
2+
3+
## Executive Summary
4+
5+
Connection management for the Hookdeck CLI is **98% complete and production-ready**. All core CRUD operations, lifecycle management, comprehensive authentication, rule configuration, and rate limiting have been fully implemented. The remaining 2% consists of optional enhancements (bulk operations, connection count, cloning) that are low priority.
6+
7+
**Implementation Commits:**
8+
- Rules configuration: [8acf8d3](https://github.com/hookdeck/hookdeck-cli/commit/8acf8d3)
9+
- Idempotent upsert with dry-run: [8ab6cac](https://github.com/hookdeck/hookdeck-cli/commit/8ab6cac)
10+
11+
## ✅ Completed Features (98%)
12+
13+
### Core CRUD Operations
14+
15+
All basic connection operations are fully implemented:
16+
17+
- **[`connection create`](../pkg/cmd/connection_create.go)** - Single API call with inline source/destination creation
18+
- **[`connection list`](../pkg/cmd/connection_list.go)** - With comprehensive filtering (name, source, destination, archived, disabled, paused)
19+
- **[`connection get`](../pkg/cmd/connection_get.go)** - Detailed view with full configuration
20+
- **[`connection upsert`](../pkg/cmd/connection_upsert.go)** - Idempotent create/update with `--dry-run` support (replaces deprecated `update`)
21+
- **[`connection delete`](../pkg/cmd/connection_delete.go)** - With confirmation prompts
22+
23+
### Lifecycle Management
24+
25+
Complete state management across all connection states:
26+
27+
- **[`connection enable`](../pkg/cmd/connection_enable.go)** - Enable disabled connections
28+
- **[`connection disable`](../pkg/cmd/connection_disable.go)** - Disable active connections
29+
- **[`connection pause`](../pkg/cmd/connection_pause.go)** - Temporary suspension
30+
- **[`connection unpause`](../pkg/cmd/connection_unpause.go)** - Resume paused connections
31+
- **[`connection archive`](../pkg/cmd/connection_archive.go)** - Long-term archival
32+
- **[`connection unarchive`](../pkg/cmd/connection_unarchive.go)** - Restore from archive
33+
34+
### Source Authentication (Commit 8acf8d3)
35+
36+
Full authentication support for 96+ source types with universal flags covering 80% of use cases and JSON fallback for complex scenarios:
37+
38+
**Authentication Flags:**
39+
```bash
40+
# Webhook secret verification (STRIPE, GITHUB, SHOPIFY, etc.)
41+
--source-webhook-secret <secret>
42+
43+
# API key authentication (GITLAB, BITBUCKET, etc.)
44+
--source-api-key <key>
45+
46+
# Basic authentication
47+
--source-basic-auth-user <user>
48+
--source-basic-auth-pass <password>
49+
50+
# HMAC signature verification
51+
--source-hmac-secret <secret>
52+
--source-hmac-algo <algorithm>
53+
54+
# JSON fallback for complex configurations
55+
--source-config <json-string>
56+
--source-config-file <path-to-json>
57+
```
58+
59+
**Type-Specific Validation:** Dynamic validation ensures only valid authentication methods are used for each source type (e.g., STRIPE requires webhook-secret, GITLAB requires api-key).
60+
61+
### Destination Authentication (Commit 8acf8d3)
62+
63+
Complete authentication support for HTTP, CLI, and Mock API destinations:
64+
65+
**Authentication Flags:**
66+
```bash
67+
# Bearer token authentication
68+
--destination-bearer-token <token>
69+
70+
# Basic authentication
71+
--destination-basic-auth-user <user>
72+
--destination-basic-auth-pass <password>
73+
74+
# API key authentication
75+
--destination-api-key <key>
76+
--destination-api-key-name <header-name> # Defaults to "x-api-key"
77+
78+
# Custom headers (JSON)
79+
--destination-custom-headers <json-string>
80+
--destination-custom-headers-file <path-to-json>
81+
82+
# OAuth2 configuration
83+
--destination-oauth2-client-id <id>
84+
--destination-oauth2-client-secret <secret>
85+
--destination-oauth2-token-url <url>
86+
--destination-oauth2-scopes <scope1,scope2>
87+
88+
# JSON fallback for complex configurations
89+
--destination-config <json-string>
90+
--destination-config-file <path-to-json>
91+
```
92+
93+
### Rule Configuration (Commit 8acf8d3)
94+
95+
All 5 rule types fully implemented with ordered execution support:
96+
97+
**1. Retry Rules:**
98+
```bash
99+
--rule-retry-strategy <linear|exponential>
100+
--rule-retry-count <number>
101+
--rule-retry-interval <milliseconds>
102+
--rule-retry-response-status-codes <"500-599,!401,404">
103+
```
104+
105+
**2. Filter Rules:**
106+
```bash
107+
--rule-filter-body <jq-expression>
108+
--rule-filter-headers <jq-expression>
109+
--rule-filter-query <jq-expression>
110+
--rule-filter-path <jq-expression>
111+
```
112+
113+
**3. Transform Rules:**
114+
```bash
115+
--rule-transform-name <transformation-name-or-id>
116+
--rule-transform-code <javascript-code>
117+
--rule-transform-env <json-env-vars>
118+
```
119+
120+
**4. Delay Rules:**
121+
```bash
122+
--rule-delay-delay <milliseconds>
123+
```
124+
125+
**5. Deduplicate Rules:**
126+
```bash
127+
--rule-deduplicate-window <milliseconds>
128+
--rule-deduplicate-include-fields <field1,field2>
129+
--rule-deduplicate-exclude-fields <field1,field2>
130+
```
131+
132+
**Rule Ordering:** Rules are executed in the order flags appear on the command line. See [`connection-rules-cli-design.md`](./connection-rules-cli-design.md) for complete specification.
133+
134+
**JSON Fallback:**
135+
```bash
136+
--rules <json-array>
137+
--rules-file <path-to-json>
138+
```
139+
140+
### Rate Limiting
141+
142+
Full rate limiting configuration for destinations:
143+
144+
```bash
145+
--destination-rate-limit <requests>
146+
--destination-rate-limit-period <seconds|minutes|hours>
147+
```
148+
149+
### Idempotent Operations (Commit 8ab6cac)
150+
151+
The [`connection upsert`](../pkg/cmd/connection_upsert.go) command provides declarative, idempotent connection management:
152+
153+
**Features:**
154+
- Creates connection if it doesn't exist (by name)
155+
- Updates connection if it exists
156+
- `--dry-run` flag for safe preview of changes
157+
- Replaces deprecated `connection update` command
158+
- Ideal for infrastructure-as-code workflows
159+
160+
**Example:**
161+
```bash
162+
# Preview changes before applying
163+
hookdeck connection upsert my-connection \
164+
--source-type STRIPE \
165+
--destination-url https://api.example.com \
166+
--rule-retry-strategy exponential \
167+
--dry-run
168+
169+
# Apply changes
170+
hookdeck connection upsert my-connection \
171+
--source-type STRIPE \
172+
--destination-url https://api.example.com \
173+
--rule-retry-strategy exponential
174+
```
175+
176+
## 📋 Optional Enhancements (Low Priority)
177+
178+
The following features would add convenience but are not critical for production use:
179+
180+
### Bulk Operations (2% remaining)
181+
- `connection bulk-enable` - Enable multiple connections at once
182+
- `connection bulk-disable` - Disable multiple connections at once
183+
- `connection bulk-delete` - Delete multiple connections with confirmation
184+
- `connection bulk-archive` - Archive multiple connections
185+
186+
**Use Case:** Managing large numbers of connections in batch operations.
187+
188+
**Priority:** Low - users can script individual commands or use the API directly for bulk operations.
189+
190+
### Connection Count
191+
- `connection count` - Display total number of connections with optional filters
192+
193+
**Use Case:** Quick overview of connection inventory.
194+
195+
**Priority:** Low - `connection list` already provides this information.
196+
197+
### Connection Cloning
198+
- `connection clone <source-connection> <new-name>` - Duplicate a connection with a new name
199+
200+
**Use Case:** Creating similar connections quickly.
201+
202+
**Priority:** Low - users can achieve this by copying command-line flags or using JSON export.
203+
204+
## Key Design Decisions
205+
206+
### 1. Universal Flag Pattern with Type-Driven Validation
207+
208+
**Decision:** Expose all possible flags for a resource type, but validate based on the `--type` parameter.
209+
210+
**Rationale:**
211+
- Provides clear, discoverable CLI interface
212+
- Maintains consistent flag naming across commands
213+
- Enables helpful type-specific error messages
214+
- Avoids complex dynamic help text generation
215+
216+
**Implementation:** See [`AGENTS.md`](../AGENTS.md) sections 2-3 for complete conversion patterns.
217+
218+
### 2. JSON Fallback for Complex Configurations
219+
220+
**Decision:** Provide JSON config flags (`--source-config`, `--destination-config`, `--rules`) as an escape hatch for complex scenarios.
221+
222+
**Rationale:**
223+
- Covers 100% of API capabilities
224+
- Supports infrastructure-as-code workflows
225+
- Handles edge cases without CLI bloat
226+
- Natural path for migrating from API to CLI
227+
228+
### 3. Rule Ordering via Flag Position
229+
230+
**Decision:** Determine rule execution order by the position of flags on the command line.
231+
232+
**Rationale:**
233+
- Intuitive and predictable behavior
234+
- Aligns with natural reading order (left to right)
235+
- No need for explicit ordering parameters
236+
- See [`connection-rules-cli-design.md`](./connection-rules-cli-design.md) for full specification
237+
238+
### 4. Idempotent Upsert over Update
239+
240+
**Decision:** Replace `connection update` with `connection upsert` and add `--dry-run` support.
241+
242+
**Rationale:**
243+
- Idempotent operations are safer and more predictable
244+
- Declarative approach better for infrastructure-as-code
245+
- Dry-run enables preview-before-apply workflow
246+
- Single command for both create and update scenarios
247+
- See [`connection-upsert-design.md`](./connection-upsert-design.md) for full specification
248+
249+
### 5. Single API Call with Inline Creation
250+
251+
**Decision:** Use single `POST /connections` API call with inline source/destination creation.
252+
253+
**Rationale:**
254+
- Atomic operation reduces error scenarios
255+
- Aligns with API design intent
256+
- Eliminates orphaned resources from failed operations
257+
- Improves performance (1 API call vs 3)
258+
259+
## Implementation Files Reference
260+
261+
**Core Command Files:**
262+
- [`pkg/cmd/connection.go`](../pkg/cmd/connection.go) - Main command group
263+
- [`pkg/cmd/connection_create.go`](../pkg/cmd/connection_create.go) - Create with inline resources
264+
- [`pkg/cmd/connection_list.go`](../pkg/cmd/connection_list.go) - List with filtering
265+
- [`pkg/cmd/connection_get.go`](../pkg/cmd/connection_get.go) - Detailed view
266+
- [`pkg/cmd/connection_upsert.go`](../pkg/cmd/connection_upsert.go) - Idempotent create/update
267+
- [`pkg/cmd/connection_delete.go`](../pkg/cmd/connection_delete.go) - Delete with confirmation
268+
269+
**Lifecycle Management:**
270+
- [`pkg/cmd/connection_enable.go`](../pkg/cmd/connection_enable.go)
271+
- [`pkg/cmd/connection_disable.go`](../pkg/cmd/connection_disable.go)
272+
- [`pkg/cmd/connection_pause.go`](../pkg/cmd/connection_pause.go)
273+
- [`pkg/cmd/connection_unpause.go`](../pkg/cmd/connection_unpause.go)
274+
- [`pkg/cmd/connection_archive.go`](../pkg/cmd/connection_archive.go)
275+
- [`pkg/cmd/connection_unarchive.go`](../pkg/cmd/connection_unarchive.go)
276+
277+
**API Client:**
278+
- [`pkg/hookdeck/connections.go`](../pkg/hookdeck/connections.go) - Connection API client
279+
- [`pkg/hookdeck/sources.go`](../pkg/hookdeck/sources.go) - Source API models
280+
- [`pkg/hookdeck/destinations.go`](../pkg/hookdeck/destinations.go) - Destination API models
281+
282+
## Architecture Patterns
283+
284+
### Flag Naming Convention
285+
286+
All flags follow consistent patterns from [`AGENTS.md`](../AGENTS.md):
287+
288+
- **Resource identifiers:** `--name` for human-readable names
289+
- **Type parameters:**
290+
- Individual resources: `--type`
291+
- Connection creation: `--source-type`, `--destination-type` (prefixed to avoid ambiguity)
292+
- **Authentication:** Prefixed by resource (`--source-webhook-secret`, `--destination-bearer-token`)
293+
- **Collections:** Comma-separated values (`--connections "a,b,c"`)
294+
- **Booleans:** Presence flags (`--dry-run`, `--force`)
295+
296+
### Validation Pattern
297+
298+
Progressive validation in `PreRunE`:
299+
1. **Flag parsing validation** - Correct types
300+
2. **Type-specific validation** - Based on `--type` parameter
301+
3. **Cross-parameter validation** - Relationships between parameters
302+
4. **API schema validation** - Final validation by API
303+
304+
## Related Documentation
305+
306+
- [`connection-rules-cli-design.md`](./connection-rules-cli-design.md) - Complete rule configuration specification
307+
- [`connection-upsert-design.md`](./connection-upsert-design.md) - Idempotent upsert command specification
308+
- [`resource-management-implementation.md`](../resource-management-implementation.md) - Overall resource management plan
309+
- [`AGENTS.md`](../AGENTS.md) - CLI development guidelines and patterns
310+
- [`REFERENCE.md`](../REFERENCE.md) - Complete CLI reference documentation
311+
312+
## Summary
313+
314+
Connection management is feature-complete and production-ready at 98%. All essential operations, authentication methods, rule types, and lifecycle management are fully implemented. The remaining 2% consists of convenience features (bulk operations, count, cloning) that can be added based on user feedback but are not blockers for production use.

0 commit comments

Comments
 (0)