Skip to content

Commit 465e541

Browse files
Copilotbaelter
Copilot
and
baelter
committed
Add comprehensive GitHub Copilot instructions with validated commands and timings
Co-authored-by: baelter <1399369+baelter@users.noreply.github.com>
1 parent 490094c commit 465e541

1 file changed

Lines changed: 179 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# AMQP Client.js Development Instructions
2+
3+
Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
4+
5+
## Project Overview
6+
AMQP client.js is a TypeScript library providing AMQP 0-9-1 client functionality for both Node.js (TCP Socket) and browsers (WebSocket). The library has zero runtime dependencies and is designed for high performance messaging.
7+
8+
## Working Effectively
9+
10+
### Prerequisites and Setup
11+
- Requires Node.js >= 16.0.0 (verified working with Node.js 20.x)
12+
- Docker and Docker Compose for RabbitMQ testing server
13+
- For browser testing: Playwright (optional, may not work in all environments)
14+
15+
### Bootstrap and Build Process
16+
Run these commands in sequence:
17+
18+
1. **Install dependencies**:
19+
```bash
20+
npm install
21+
```
22+
- Takes ~16 seconds
23+
- Automatically runs the build process via `prepare` script
24+
- NEVER CANCEL: Set timeout to 30+ minutes for initial install
25+
26+
2. **Manual build** (if needed):
27+
```bash
28+
npm run build
29+
```
30+
- Takes ~5.4 seconds
31+
- NEVER CANCEL: Set timeout to 10+ minutes
32+
- Creates three output formats:
33+
- ES modules in `lib/mjs/`
34+
- CommonJS modules in `lib/cjs/`
35+
- TypeScript declarations in `types/`
36+
- Browser bundle in `dist/`
37+
38+
3. **Start RabbitMQ services**:
39+
```bash
40+
docker compose up -d
41+
```
42+
- Takes ~11 seconds for first startup
43+
- NEVER CANCEL: Set timeout to 15+ minutes for Docker image pulls
44+
- Starts RabbitMQ server on ports 5671 (TLS) and 5672 (plain)
45+
- Starts WebSocket TCP relay on port 15670
46+
47+
### Testing
48+
49+
#### Node.js Tests
50+
```bash
51+
npm test
52+
```
53+
- Takes ~15 seconds
54+
- NEVER CANCEL: Set timeout to 30+ minutes
55+
- Runs Node.js tests with coverage using Vitest
56+
- **EXPECTED**: 2 TLS-related tests may fail if certificates are not set up (normal in development)
57+
- All other tests should pass when RabbitMQ is running
58+
59+
#### Browser Tests
60+
```bash
61+
npx playwright install --with-deps chromium
62+
npm run test-browser
63+
```
64+
- **WARNING**: Playwright installation often fails in CI environments
65+
- Browser tests require WebSocket functionality
66+
- NEVER CANCEL: Playwright install can take 30+ minutes
67+
- Only attempt browser tests if Playwright installs successfully
68+
69+
#### Linting
70+
```bash
71+
npm run lint
72+
```
73+
- Takes ~1.8 seconds
74+
- Uses ESLint with TypeScript support
75+
- Must pass before committing (CI requirement)
76+
77+
#### Documentation Generation
78+
```bash
79+
npm run docs
80+
```
81+
- Takes ~3.4 seconds
82+
- Generates API documentation in `docs/` directory
83+
- Uses TypeDoc
84+
85+
### Validation Scenarios
86+
After making changes, always run this validation sequence:
87+
88+
1. **Build validation**: `npm run build` - ensure TypeScript compilation succeeds
89+
2. **Test validation**: `npm test` - run Node.js tests (RabbitMQ must be running)
90+
3. **Lint validation**: `npm run lint` - ensure code style compliance
91+
4. **Functionality validation**: Test actual AMQP operations (see examples below)
92+
93+
### Manual Functional Testing
94+
Always test functionality manually when making changes to core AMQP logic:
95+
96+
```javascript
97+
import { AMQPClient } from './lib/mjs/index.js';
98+
99+
// Basic publish/consume test
100+
const amqp = new AMQPClient("amqp://localhost");
101+
const conn = await amqp.connect();
102+
const ch = await conn.channel();
103+
const q = await ch.queue("test-queue");
104+
await q.publish("test message");
105+
const consumer = await q.subscribe({noAck: true}, (msg) => {
106+
console.log("Received:", msg.bodyString());
107+
});
108+
// Clean up: consumer.cancel(), q.delete(), conn.close()
109+
```
110+
111+
## Important Files and Structure
112+
113+
### Source Code (`src/`)
114+
- `amqp-socket-client.ts` - Node.js TCP client implementation
115+
- `amqp-websocket-client.ts` - Browser WebSocket client implementation
116+
- `amqp-channel.ts` - AMQP channel implementation
117+
- `amqp-queue.ts` - Queue operations
118+
- `amqp-message.ts` - Message handling
119+
- `index.ts` - Main exports
120+
121+
### Tests (`test/`)
122+
- `test.ts` - Main Node.js test suite
123+
- `tls.ts` - TLS connection tests (may fail without certificates)
124+
125+
### Browser Tests (`test-browser/`)
126+
- `websocket.ts` - WebSocket client tests
127+
128+
### Configuration Files
129+
- `package.json` - Build scripts and dependencies
130+
- `tsconfig.json` - TypeScript configuration
131+
- `vitest.config.ts` - Node.js test configuration
132+
- `vitest.config.browser.ts` - Browser test configuration
133+
- `docker-compose.yml` - RabbitMQ test environment
134+
135+
### Build Output
136+
- `lib/mjs/` - ES module builds
137+
- `lib/cjs/` - CommonJS builds
138+
- `types/` - TypeScript declarations
139+
- `dist/` - Browser-ready bundles
140+
141+
## Common Issues and Solutions
142+
143+
### RabbitMQ Connection Issues
144+
- Ensure `docker compose up -d` has been run
145+
- Check containers are healthy: `docker compose ps`
146+
- RabbitMQ takes ~20 seconds to fully start
147+
148+
### Build Failures
149+
- Run `npm run prebuild` to clean build directories
150+
- Ensure TypeScript has no compilation errors
151+
- Check Node.js version is >= 16.0.0
152+
153+
### Test Failures
154+
- TLS tests failing: Expected if mkcert certificates not installed
155+
- Connection errors: Ensure RabbitMQ is running via Docker
156+
- WebSocket tests failing: Expected if Playwright not installed
157+
158+
### Browser Testing Limitations
159+
- WebSocket client requires browser environment or WebSocket polyfill
160+
- Playwright installation may fail in some CI environments
161+
- Browser bundle available in `dist/amqp-websocket-client.mjs`
162+
163+
## Performance Notes
164+
- Library has zero runtime dependencies
165+
- Supports high-throughput messaging (300k+ msgs/sec publish, 512k+ msgs/sec consume)
166+
- Uses DataView for binary protocol parsing (browser compatibility)
167+
- Optimized frame buffering for WebSocket connections
168+
169+
## Development Workflow
170+
1. Start RabbitMQ: `docker compose up -d`
171+
2. Install dependencies: `npm install`
172+
3. Make changes to `src/` files
173+
4. Build: `npm run build`
174+
5. Test: `npm test`
175+
6. Lint: `npm run lint`
176+
7. Manual validation with real AMQP operations
177+
8. Clean up: `docker compose down`
178+
179+
Always run the full validation sequence before committing changes. The CI pipeline (.github/workflows/ci.yml) will run all these steps and must pass for merge approval.

0 commit comments

Comments
 (0)