Skip to content

Commit 29db244

Browse files
Copilotcubap
Copilot
and
cubap
authored
Add comprehensive GitHub Copilot instructions with coding style guidelines for RERUM API development (#208)
* Initial plan * Create comprehensive GitHub Copilot instructions with validated commands and timing Co-authored-by: cubap <1119165+cubap@users.noreply.github.com> * Add coding style guidelines to Copilot instructions Co-authored-by: cubap <1119165+cubap@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: cubap <1119165+cubap@users.noreply.github.com>
1 parent 7535c17 commit 29db244

File tree

1 file changed

+201
-0
lines changed

1 file changed

+201
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# RERUM API v1 Server
2+
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.
3+
4+
RERUM API v1 is a NodeJS web service for interaction with the RERUM digital object repository. It stores JSON-LD objects including Web Annotations, SharedCanvas/IIIF objects, FOAF Agents, and any valid JSON objects. Visit [rerum.io](https://rerum.io) for general information and [store.rerum.io](https://store.rerum.io/) for the hosted public instance.
5+
6+
## Working Effectively
7+
8+
### Prerequisites
9+
- **CRITICAL**: Node.js version 22.17.1 or higher is required (specified in package.json engines: ">=22.12.0")
10+
- MongoDB database connection for full API functionality
11+
- Git for version control
12+
13+
### Bootstrap and Setup
14+
1. **Install Node.js 22.17.1**:
15+
```bash
16+
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
17+
source ~/.bashrc
18+
nvm install 22.17.1
19+
nvm use 22.17.1
20+
```
21+
22+
2. **Install dependencies**:
23+
```bash
24+
npm install
25+
```
26+
- NEVER CANCEL: Takes 2-5 seconds. Set timeout to 30+ seconds.
27+
28+
3. **Create .env configuration file** (required for operation):
29+
```bash
30+
# Create .env file in repository root
31+
RERUM_API_VERSION=1.0.0
32+
RERUM_BASE=http://localhost:3005
33+
RERUM_PREFIX=http://localhost:3005/v1/
34+
RERUM_ID_PREFIX=http://localhost:3005/v1/id/
35+
RERUM_AGENT_CLAIM=http://localhost:3005/agent
36+
RERUM_CONTEXT=http://localhost:3005/v1/context.json
37+
RERUM_API_DOC=http://localhost:3005/v1/API.html
38+
MONGO_CONNECTION_STRING=mongodb://localhost:27017/test
39+
MONGODBNAME=test_rerum
40+
MONGODBCOLLECTION=test_collection
41+
DOWN=false
42+
READONLY=false
43+
PORT=3005
44+
CLIENTID=test_client_id
45+
RERUMSECRET=test_secret
46+
BOT_TOKEN=test_bot_token
47+
BOT_AGENT=test_bot_agent
48+
AUDIENCE=test_audience
49+
ISSUER_BASE_URL=https://test.auth0.com/
50+
```
51+
52+
### Testing
53+
- **Route and Static File Tests** (work without database):
54+
```bash
55+
npm run runtest -- __tests__/routes_mounted.test.js
56+
```
57+
- NEVER CANCEL: Takes 30 seconds. Set timeout to 60+ seconds.
58+
59+
- **Full Test Suite** (requires MongoDB connection):
60+
```bash
61+
npm run runtest
62+
```
63+
- NEVER CANCEL: Takes 25+ minutes (many tests timeout without MongoDB). Set timeout to 45+ minutes.
64+
- **CRITICAL**: Most tests fail with 5-second timeouts if MongoDB is not connected - this is expected behavior in development environment.
65+
66+
### Running the Application
67+
- **Start the server**:
68+
```bash
69+
npm start
70+
```
71+
- Server runs on `http://localhost:3005` (configurable via PORT in .env)
72+
- Takes 2-3 seconds to start
73+
- Displays "LISTENING ON 3005" when ready
74+
75+
- **Stop the server**: `CTRL + C` or `CTRL + X`
76+
77+
## Validation
78+
79+
### Manual Testing Scenarios
80+
After making changes, ALWAYS validate these scenarios:
81+
82+
1. **Server Startup**:
83+
```bash
84+
npm start
85+
# Should display "LISTENING ON 3005" within 3 seconds
86+
```
87+
88+
2. **Static File Serving**:
89+
```bash
90+
curl -I http://localhost:3005/v1/API.html
91+
curl -I http://localhost:3005/v1/context.json
92+
curl -I http://localhost:3005/
93+
# Should return 200 OK responses
94+
```
95+
96+
3. **Route Mounting**:
97+
```bash
98+
npm run runtest -- __tests__/routes_mounted.test.js
99+
# Should pass all 17 tests in ~30 seconds
100+
```
101+
102+
4. **API Authentication Behavior**:
103+
```bash
104+
# Test create endpoint (matches example from Talend API Tester)
105+
curl -X POST http://localhost:3005/v1/api/create -H "Content-Type: application/json" -d '{"@":"5"}'
106+
# Should return 401 Unauthorized with proper auth message
107+
108+
# Test with invalid token
109+
curl -X POST http://localhost:3005/v1/api/create -H "Authorization: Bearer fake_token" -H "Content-Type: application/json" -d '{"@":"5"}'
110+
# Should return 401 with "This token did not contain a known RERUM agent"
111+
```
112+
113+
5. **Database-dependent endpoints** (if MongoDB available):
114+
```bash
115+
curl -X POST http://localhost:3005/v1/api/query -H "Content-Type: application/json" -d '{"test": "value"}'
116+
# Should either work with 200 OK or return "Topology is closed" error without MongoDB
117+
```
118+
119+
### Working Without MongoDB
120+
- **WORKS**: Server startup, static file serving, route mounting tests, authentication handling
121+
- **FAILS**: All database operations (/query, /create, /update, /delete, /id/{id}, etc.) return "Topology is closed" errors
122+
- **FOR DEVELOPMENT**: Use route mounting tests to validate routing changes without requiring database setup
123+
124+
## Common Tasks
125+
126+
### Key Directories
127+
- `/routes/` - Route handlers and API endpoints (Express routes)
128+
- `/controllers/` - Business logic controllers (CRUD operations, GOG-specific controllers)
129+
- `/database/` - Database connection and utilities (MongoDB integration)
130+
- `/auth/` - Authentication middleware (Auth0 JWT handling)
131+
- `/public/` - Static files (API.html, context.json, etc.)
132+
- `/__tests__/` - Test files (Jest test suites)
133+
- `/bin/rerum_v1.js` - Main application entry point
134+
135+
### Important Files to Monitor
136+
- `package.json` - Dependencies and scripts (requires Node.js 22+)
137+
- `app.js` - Express application setup and middleware configuration
138+
- `routes/api-routes.js` - Main API route definitions and mounting
139+
- `.env` - Configuration (create from template above)
140+
- `jest.config.js` - Test configuration (VM modules experimental)
141+
142+
### Architecture Notes
143+
- **RESTful API**: Standard HTTP methods (GET, POST, PUT, PATCH, DELETE)
144+
- **Authentication**: Auth0 JWT bearer tokens required for write operations
145+
- **Database**: MongoDB for persistent storage, versioned objects
146+
- **Static Files**: Served directly from `/public` directory
147+
- **CORS**: Fully open ("*") for cross-origin requests
148+
- **Specialized Routes**: Gallery of Glosses (GOG) specific endpoints in `_gog_*.js` files
149+
150+
### Coding Style Guidelines
151+
- **Semicolons**: Avoid unnecessary semicolons (e.g., at the end of most lines)
152+
- **Control Flow**: Prefer guard clauses over if/else statements when the meaning is clear
153+
- **Modern JavaScript**: Use optional chaining (`?.`) and nullish coalescing (`??`) operators and ternaries for concise code when it doesn't compromise readability
154+
- **Language**: Use inclusive language and labels throughout the codebase
155+
- **Attribution**: Include attribution for contributed code or borrowed code at the top of each file
156+
157+
### Development Workflow
158+
1. **After routing changes**: Always run basic route tests: `npm run runtest -- __tests__/routes_mounted.test.js`
159+
2. **After configuration changes**: Test server startup: `npm start` (should display "LISTENING ON 3005")
160+
3. **After API changes**: Test endpoints with curl as shown in validation scenarios
161+
4. **For Auth0 integration testing**: Contact Research Computing Group at research.computing@slu.edu
162+
5. **API reference**: Use documentation at http://localhost:3005/v1/API.html
163+
164+
### Complete Change Validation Example
165+
```bash
166+
# 1. Make your changes to routes/controllers
167+
# 2. Test route mounting
168+
npm run runtest -- __tests__/routes_mounted.test.js
169+
170+
# 3. Test server startup
171+
npm start
172+
# Should show "LISTENING ON 3005"
173+
174+
# 4. In another terminal, test endpoints
175+
curl -I http://localhost:3005/v1/API.html
176+
curl -X POST http://localhost:3005/v1/api/create -H "Content-Type: application/json" -d '{"test": "value"}'
177+
178+
# 5. Stop server: CTRL + C
179+
```
180+
181+
### CI/CD Notes
182+
- GitHub Actions run on Node.js 22
183+
- Tests run with: `npm install && npm run runtest`
184+
- Deploy uses PM2 for process management
185+
- Development environment available via PR to main branch
186+
- Production deploys on push to main branch
187+
188+
### Troubleshooting
189+
- **"Unsupported engine" warnings**: Expected with Node.js 22+ due to express-oauth2-jwt-bearer package
190+
- **Test timeouts**: Expected without MongoDB connection - focus on route mounting tests for development
191+
- **Port conflicts**: Change PORT in .env file if 3005 is taken
192+
- **JWT/Auth errors**: Expected in development - requires Auth0 setup for full functionality
193+
- **"Cannot use import statement outside a module"**: Use `npm run runtest` (not `npm test`) - requires experimental VM modules
194+
- **"Jest did not exit" warning**: Normal behavior - tests complete successfully despite this warning
195+
196+
## Build and Timing Expectations
197+
- **npm install**: 2-5 seconds, NEVER CANCEL (timeout: 30+ seconds)
198+
- **Basic tests**: 30 seconds, NEVER CANCEL (timeout: 60+ seconds)
199+
- **Full test suite**: 25+ minutes with timeouts, NEVER CANCEL (timeout: 45+ minutes)
200+
- **Server startup**: 2-3 seconds
201+
- **No build step required** - Direct Node.js execution

0 commit comments

Comments
 (0)