Skip to content

Design: Fix 9 milestone issues (docs, tests, query limits) #40

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jstirnaman wants to merge 24 commits into
base: main
Choose a base branch
from
Open

Design: Fix 9 milestone issues (docs, tests, query limits) #40

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
d0ad46e
feat: migrate to InfluxDB 3 Core with influxdb3-javascript client
claude Feb 9, 2026
2431ad9
fix: use Point class from influxdb3-client and fix Node.js crypto
claude Feb 9, 2026
324063a
Merge main to resolve package.json conflict
claude Feb 9, 2026
41c7e1a
Apply jstirnaman review suggestions for InfluxDB 3 migration (#20)
jstirnaman Feb 9, 2026
b878619
Merge branch 'main' into claude/influxdb3-core-migration-pMqwy
jstirnaman Feb 9, 2026
07c514a
Update pages/api/devices/create.js
jstirnaman Feb 10, 2026
85b5b40
Update pages/api/devices/create.js
jstirnaman Feb 10, 2026
f9cf64a
fix: address Copilot security review issues and add tests
claude Feb 10, 2026
d885cd8
docs: update README for InfluxDB 3 Core migration
claude Feb 10, 2026
a640134
Merge influxdb3-migration-v3 into influxdb3-core-migration
jstirnaman Feb 10, 2026
b1f0512
feat: migrate to InfluxDB 3 Core with influxdb3-javascript client (#18)
jstirnaman Feb 10, 2026
f6c3e04
chore: add Claude Code configuration and Docker Compose for InfluxDB 3
jstirnaman Feb 10, 2026
a72bf4b
Merge remote-tracking branch 'origin/release/influxdb3-core-3.8.1' in…
jstirnaman Feb 10, 2026
4b74cc5
Update CLAUDE.md
jstirnaman Feb 10, 2026
7b98aaa
Update compose.yaml
jstirnaman Feb 10, 2026
49f0d96
Update AGENTS.md
jstirnaman Feb 10, 2026
1f093ea
Update AGENTS.md
jstirnaman Feb 10, 2026
14d4f71
Update CLAUDE.md
jstirnaman Feb 10, 2026
a2c5937
Update AGENTS.md
jstirnaman Feb 10, 2026
c77d106
chore: add .worktrees to .gitignore
jstirnaman Feb 10, 2026
dcdfb26
fix: remove duplicate deviceId declaration in create.js
jstirnaman Feb 17, 2026
4e968f2
docs: refactor AI instructions into modular docs/ structure
jstirnaman Feb 27, 2026
70b321b
docs: add migration design for InfluxDB 3 Core with caching, plugins,…
jstirnaman Feb 27, 2026
492ae7e
docs: add implementation plan for caching, plugins, and Enterprise
jstirnaman Feb 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions .claude/settings.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
{
"permissions": {
"allow": [
"Bash(npm:*)",
"Bash(yarn:*)",
"Bash(npx:*)",
"Bash(node:*)",
"Bash(curl:*)",
"Bash(gh:*)",
"Bash(jq:*)",
"Bash(mkdir:*)",
"Bash(docker:*)",
"Bash(docker compose:*)",
"Edit",
"Read",
"Write",
"Grep",
"Glob",
"LS"
],
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)"
],
"ask": [
"Bash(git push:*)"
]
}
}
195 changes: 195 additions & 0 deletions .claude/skills/run-tests/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,195 @@
---
name: run-tests
description: Run API tests against InfluxDB 3 Core. Handles service initialization, database setup, and test execution.
author: InfluxData
version: "1.0"
---

# Run Tests Skill

## Purpose

This skill guides running the IoT API test suite against a local InfluxDB 3 Core instance. It covers service setup, database creation, and test execution.
Comment on lines +3 to +12
Copy link

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The skill description and purpose incorrectly state that tests run "against InfluxDB 3 Core" and require a database instance, which contradicts issue #33 that this PR claims to resolve.

The test suite uses mocks (see tests/api.test.js lines 13-30) and runs without any database connection. According to the design document, the skill should be updated to describe the mocked/unit test workflow, with database setup moved to an optional section for manual testing.

Copilot uses AI. Check for mistakes.

## Quick Reference

| Task | Command |
|------|---------|
| Start InfluxDB 3 | `docker compose up -d influxdb3-core` |
| Check status | `curl -i http://localhost:8181/health` |
| Run tests | `yarn test` |
| View logs | `docker logs influxdb3-core` |

## Complete Setup Workflow

### 1. Initialize InfluxDB 3 Core

```bash
# Create required directories
mkdir -p test/.influxdb3/core/data test/.influxdb3/core/plugins

# Generate admin token (first time only)
openssl rand -hex 32 > test/.influxdb3/core/.token
chmod 600 test/.influxdb3/core/.token

# Start the container
docker compose up -d influxdb3-core

# Wait for healthy status
docker compose ps
```

### 2. Create Databases

```bash
# Get the token
TOKEN=$(cat test/.influxdb3/core/.token)

# Create main database
curl -X POST "http://localhost:8181/api/v3/configure/database" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"db": "iot_center"}'

# Create auth database
curl -X POST "http://localhost:8181/api/v3/configure/database" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"db": "iot_center_auth"}'

# Verify databases exist
curl "http://localhost:8181/api/v3/configure/database?format=json" \
-H "Authorization: Bearer $TOKEN"
```

### 3. Configure Environment

Create `.env.local` if it doesn't exist:

```bash
cat > .env.local << EOF
INFLUX_HOST=http://localhost:8181
INFLUX_TOKEN=$(cat test/.influxdb3/core/.token)
INFLUX_DATABASE=iot_center
INFLUX_DATABASE_AUTH=iot_center_auth
EOF
```

### 4. Run Tests

```bash
# Install dependencies (if needed)
yarn

# Run the test suite
yarn test

# Run with verbose output
yarn test --verbose

# Run specific test file
yarn test __tests__/api.test.js
```

## Troubleshooting

### Container Won't Start

**Symptom:** Container exits immediately

**Check:**
```bash
# View logs
docker logs influxdb3-core

# Verify directories exist
ls -la test/.influxdb3/core/

# Verify token file exists
cat test/.influxdb3/core/.token
```

**Common fixes:**
- Create missing directories: `mkdir -p test/.influxdb3/core/data test/.influxdb3/core/plugins`
- Generate token: `openssl rand -hex 32 > test/.influxdb3/core/.token`

### 401 Unauthorized

**Symptom:** API calls return 401

**Check:**
```bash
# Verify token matches
echo "Token in file: $(cat test/.influxdb3/core/.token)"
echo "Token in .env.local: $(grep INFLUX_TOKEN .env.local)"

# Test with token directly
curl -i http://localhost:8181/api/v3/configure/database \
-H "Authorization: Bearer $(cat test/.influxdb3/core/.token)"
Comment on lines +122 to +128
Copy link

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The troubleshooting commands use cat test/.influxdb3/core/.token and grep INFLUX_TOKEN .env.local, which violate the Read(./.env.*) deny rule in .claude/settings.json. This is issue #32 and #37 that should be resolved by this PR.

According to the design document, these commands should be replaced with environment variable checks like echo "INFLUX_TOKEN: ${INFLUX_TOKEN:-'(not set)'}" or similar approaches that don't require reading .env files directly.

Suggested change
# Verify token matches
echo "Token in file: $(cat test/.influxdb3/core/.token)"
echo "Token in .env.local: $(grep INFLUX_TOKEN .env.local)"
# Test with token directly
curl -i http://localhost:8181/api/v3/configure/database \
-H "Authorization: Bearer $(cat test/.influxdb3/core/.token)"
# Verify INFLUX_TOKEN environment variable is set
echo "INFLUX_TOKEN: ${INFLUX_TOKEN:-'(not set)'}"
# Test with token directly from environment
curl -i http://localhost:8181/api/v3/configure/database \
-H "Authorization: Bearer ${INFLUX_TOKEN:?INFLUX_TOKEN is not set}"

Copilot uses AI. Check for mistakes.
```

### Database Not Found

**Symptom:** Tests fail with "database not found"

**Fix:** Create the required databases:
```bash
TOKEN=$(cat test/.influxdb3/core/.token)
curl -X POST "http://localhost:8181/api/v3/configure/database" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"db": "iot_center"}'
curl -X POST "http://localhost:8181/api/v3/configure/database" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"db": "iot_center_auth"}'
```

### Port Already in Use

**Symptom:** "port is already allocated"

**Fix:**
```bash
# Find what's using the port
lsof -i :8181

# Stop existing container
docker compose down
```

## Clean Slate

To start fresh:

```bash
# Stop and remove containers
docker compose down

# Remove data (WARNING: deletes all data)
rm -rf test/.influxdb3/core/data/*

# Regenerate token
openssl rand -hex 32 > test/.influxdb3/core/.token

# Start fresh
docker compose up -d influxdb3-core
```

## Test Configuration

The test suite uses these environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `INFLUX_HOST` | `http://localhost:8181` | InfluxDB 3 API URL |
| `INFLUX_TOKEN` | (from `.env.local`) | Admin token |
| `INFLUX_DATABASE` | `iot_center` | Main data database |
| `INFLUX_DATABASE_AUTH` | `iot_center_auth` | Device auth database |
Copy link

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The database name iot_center_auth is used throughout this file (lines 58, 74, 145, 188), but this is incorrect per issue #34. The project's default in .env.development and throughout the codebase is iot_center_devices for the auth database (INFLUX_DATABASE_AUTH).

According to the design document, all references to iot_center_auth should be changed to iot_center_devices to match the project defaults and prevent "database not found" errors.

Suggested change
| `INFLUX_DATABASE_AUTH` | `iot_center_auth` | Device auth database |
| `INFLUX_DATABASE_AUTH` | `iot_center_devices` | Device auth database |

Copilot uses AI. Check for mistakes.

## Related Files

- **Docker Compose**: `compose.yaml`
- **Test suite**: `__tests__/api.test.js`
- **Environment defaults**: `.env.development`
- **Local overrides**: `.env.local` (gitignored)
13 changes: 10 additions & 3 deletions .env.development
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,12 @@
# Development environment non-secret defaults
# InfluxDB 3 Core configuration

INFLUX_URL=http://localhost:8086
INFLUX_BUCKET=iot_center
INFLUX_BUCKET_AUTH=iot_center_devices
# InfluxDB 3 server URL (default port is 8181)
INFLUX_HOST=http://localhost:8181

# Database names (equivalent to v2 buckets)
INFLUX_DATABASE=iot_center
INFLUX_DATABASE_AUTH=iot_center_devices

# Token should be set in .env.local (not committed to git)
# INFLUX_TOKEN=your_admin_token_here
47 changes: 47 additions & 0 deletions .github/INSTRUCTIONS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# AI Instructions Navigation Guide

This repository has multiple instruction files for different AI tools and use cases.

## Quick Navigation

| If you are... | Start here |
|---------------|------------|
| **GitHub Copilot** | [../AGENTS.md](../AGENTS.md) |
| **Claude, ChatGPT, Gemini** | [../AGENTS.md](../AGENTS.md) |
| **Claude with MCP** | [../CLAUDE.md](../CLAUDE.md) |

## File Organization

```
iot-api-js/
├── docs/ # Detailed documentation
│ ├── architecture.md # System design, project structure
│ ├── development.md # Setup, testing, debugging
│ ├── api-reference.md # API endpoints
│ ├── code-patterns.md # InfluxDB client usage
│ └── contributing.md # Style guidelines
├── .claude/
│ ├── settings.json # Claude permissions
│ └── skills/run-tests/SKILL.md # Test execution workflow
├── .github/
│ └── INSTRUCTIONS.md # THIS FILE
├── AGENTS.md # AI assistant quick reference
├── CLAUDE.md # Claude with MCP quick reference
└── README.md # User-facing documentation
```

## Documentation

| Topic | Location |
|-------|----------|
| System architecture | [../docs/architecture.md](../docs/architecture.md) |
| Development setup | [../docs/development.md](../docs/development.md) |
| API endpoints | [../docs/api-reference.md](../docs/api-reference.md) |
| Code patterns | [../docs/code-patterns.md](../docs/code-patterns.md) |
| Contributing | [../docs/contributing.md](../docs/contributing.md) |

## Getting Started

1. **New to the repository?** Start with [../README.md](../README.md)
2. **Using AI assistants?** Read [../AGENTS.md](../AGENTS.md) then explore [../docs/](../docs/)
3. **Using Claude with MCP?** Check [../CLAUDE.md](../CLAUDE.md) and [../.claude/](../.claude/)
6 changes: 6 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,3 +28,9 @@ yarn-error.log*
.env.development.local
.env.test.local
.env.production.local

# InfluxDB 3 local data
test/.influxdb3/

# Git worktrees
.worktrees/
40 changes: 40 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# IoT API JS - AI Assistant Guide

Sample application for InfluxData tutorials demonstrating REST APIs with InfluxDB 3 Core.

**Target audience:** Developers learning to build IoT applications with InfluxDB 3.

## Quick Reference

| Task | Command |
|------|---------|
| Install | `yarn` |
| Dev server | `yarn dev -p 5200` |
| Run tests | `yarn test` |
| Start InfluxDB | `docker compose up -d influxdb3-core` |

## Key Files

| File | Purpose |
|------|---------|
| `lib/influxdb.js` | InfluxDB client factory and helpers |
| `pages/api/devices/create.js` | Device registration endpoint |
| `pages/api/devices/_devices.js` | Shared device query logic |
| `pages/api/devices/[[...deviceParams]].js` | Device CRUD operations |
| `__tests__/api.test.js` | API integration tests |
Comment on lines +23 to +24
Copy link

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The file descriptions in the Key Files table are incorrect, which contradicts the fixes described in the design document for issues #35 and #30:

  1. Line 46: Says "[[...deviceParams]].js" handles "Device CRUD operations", but the actual implementation only supports GET (for device listing) and POST (for measurements queries). There is no DELETE endpoint. This should be updated to "Device GET and measurement queries" or similar.

  2. Line 47: Says "measurements/index.js" is "Telemetry query endpoint", but this file exports a getMeasurements() helper function and is not a Next.js API endpoint (it has no default export handler). This should be "Shared telemetry query helper" as specified in issue pages/api/measurements/index.js is listed as a “Telemetry query endpoint”, but it doesn’t export a default Next.js API handler (it exports getMeasurements()), so it isn’t directly an endpoint. Consider rewording this as a shared telemetry query helper, or add an actual /api/measurements route if that’s intended. #35.

  3. Line 48: Says "tests/api.test.js" is "API integration tests", but the tests mock the InfluxDB client and run without a database. This should be "API unit tests (mocked)" as specified in issues The skill describes running the test suite “against a local InfluxDB 3 Core instance”, but the only test file (__tests__/api.test.js) mocks the InfluxDB client and can run without any database. Please either (a) adjust this skill to describe the mocked/unit test workflow, or (b) add a separate integration test target and clarify which tests require InfluxDB. #33 and This section instructs starting InfluxDB 3 before yarn test, but __tests__/api.test.js mocks ../lib/influxdb and doesn’t require a live database. Update guidance to reflect that unit tests run without InfluxDB, and optionally document a separate integration test workflow if needed. #36.

Suggested change
| `pages/api/devices/[[...deviceParams]].js` | Device CRUD operations |
| `pages/api/measurements/index.js` | Telemetry query endpoint |
| `__tests__/api.test.js` | API integration tests |
| `pages/api/devices/[[...deviceParams]].js` | Device GET and measurement queries |
| `pages/api/measurements/index.js` | Shared telemetry query helper |
| `__tests__/api.test.js` | API unit tests (mocked) |

Copilot uses AI. Check for mistakes.

## Documentation

| Topic | Location |
|-------|----------|
| System architecture | [docs/architecture.md](docs/architecture.md) |
| Development setup | [docs/development.md](docs/development.md) |
| API endpoints | [docs/api-reference.md](docs/api-reference.md) |
| Code patterns | [docs/code-patterns.md](docs/code-patterns.md) |
| Contributing | [docs/contributing.md](docs/contributing.md) |

## Other Resources

- [CLAUDE.md](CLAUDE.md) - For Claude with MCP
- [README.md](README.md) - User-facing documentation
- [.github/INSTRUCTIONS.md](.github/INSTRUCTIONS.md) - Navigation guide
38 changes: 38 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# IoT API JS - Claude Instructions

Next.js REST API demonstrating InfluxDB 3 Core integration for IoT device data.

## Quick Reference

| Task | Command |
|------|---------|
| Install | `yarn` |
| Dev server | `yarn dev -p 5200` |
| Run tests | `yarn test` |
| Start InfluxDB | `docker compose up -d influxdb3-core` |

## Key Files

| File | Purpose |
|------|---------|
| `lib/influxdb.js` | Client factory and query/write helpers |
| `pages/api/devices/create.js` | Device registration |
| `pages/api/devices/_devices.js` | Shared device queries |
| `pages/api/devices/[[...deviceParams]].js` | Device CRUD + measurements |

## Documentation

| Topic | Location |
|-------|----------|
| System architecture | [docs/architecture.md](docs/architecture.md) |
| Development setup | [docs/development.md](docs/development.md) |
| API endpoints | [docs/api-reference.md](docs/api-reference.md) |
| Code patterns | [docs/code-patterns.md](docs/code-patterns.md) |
| Contributing | [docs/contributing.md](docs/contributing.md) |
| Testing workflow | [.claude/skills/run-tests/SKILL.md](.claude/skills/run-tests/SKILL.md) |

## Other Resources

- [AGENTS.md](AGENTS.md) - Guide for general AI assistants
- [.github/INSTRUCTIONS.md](.github/INSTRUCTIONS.md) - Navigation guide
- [.claude/](.claude/) - Claude Code settings and skills
Loading