107 lines
3.2 KiB
Markdown
107 lines
3.2 KiB
Markdown
# apn-relay Agent Guide
|
|
|
|
This file defines package-specific guidance for agents working in `packages/apn-relay`.
|
|
|
|
## Scope And Precedence
|
|
|
|
- Follow root `AGENTS.md` first.
|
|
- This file provides stricter package-level conventions for relay service work.
|
|
- If future local guides are added, closest guide wins.
|
|
|
|
## Project Overview
|
|
|
|
- Minimal APNs relay service (Hono + Bun + PlanetScale via Drizzle).
|
|
- Core routes:
|
|
- `GET /health`
|
|
- `GET /`
|
|
- `POST /v1/device/register`
|
|
- `POST /v1/device/unregister`
|
|
- `POST /v1/event`
|
|
|
|
## Commands
|
|
|
|
Run all commands from `packages/apn-relay`.
|
|
|
|
- Install deps: `bun install`
|
|
- Start relay locally: `bun run dev`
|
|
- Typecheck: `bun run typecheck`
|
|
- DB connectivity check: `bun run db:check`
|
|
|
|
## Build / Test Expectations
|
|
|
|
- There is no dedicated package test script currently.
|
|
- Required validation for behavior changes:
|
|
- `bun run typecheck`
|
|
- `bun run db:check` when DB/env changes are involved
|
|
- manual endpoint verification against `/health`, `/v1/device/register`, `/v1/event`
|
|
|
|
## Single-Test Guidance
|
|
|
|
- No single-test command exists for this package today.
|
|
- For focused checks, run endpoint-level manual tests against a local dev server.
|
|
|
|
## Code Style Guidelines
|
|
|
|
### Formatting / Structure
|
|
|
|
- Keep handlers compact and explicit.
|
|
- Prefer small local helpers for repeated route logic.
|
|
- Avoid broad refactors when a targeted fix is enough.
|
|
|
|
### Types / Validation
|
|
|
|
- Validate request bodies with `zod` at route boundaries.
|
|
- Keep payload and DB row shapes explicit and close to usage.
|
|
- Avoid `any`; narrow unknown input immediately after parsing.
|
|
|
|
### Naming
|
|
|
|
- Follow existing concise naming in this package (`reg`, `unreg`, `evt`, `row`, `key`).
|
|
- For DB columns, keep snake_case alignment with schema.
|
|
|
|
### Error Handling
|
|
|
|
- Return clear JSON errors for invalid input.
|
|
- Keep handler failures observable via `app.onError` and structured logs.
|
|
- Do not leak secrets in responses or logs.
|
|
|
|
### Logging
|
|
|
|
- Log delivery lifecycle at key checkpoints:
|
|
- registration/unregistration attempts
|
|
- event fanout start/end
|
|
- APNs send failures and retries
|
|
- Mask sensitive values; prefer token suffixes and metadata.
|
|
|
|
### APNs Environment Rules
|
|
|
|
- Keep APNs env explicit per registration (`sandbox` / `production`).
|
|
- For `BadEnvironmentKeyInToken`, retry once with flipped env and persist correction.
|
|
- Avoid infinite retry loops; one retry max per delivery attempt.
|
|
|
|
## Database Conventions
|
|
|
|
- Schema is in `src/schema.sql.ts`.
|
|
- Keep table/column names snake_case.
|
|
- Maintain index naming consistency with existing schema.
|
|
- For upserts, update only fields required by current behavior.
|
|
|
|
## API Behavior Expectations
|
|
|
|
- `register`/`unregister` must be idempotent.
|
|
- `event` should return success envelope even when no devices are registered.
|
|
- Delivery logs should capture per-attempt result and error payload.
|
|
|
|
## Operational Notes
|
|
|
|
- Ensure `APNS_PRIVATE_KEY` supports escaped newline format (`\n`) and raw multiline.
|
|
- Validate that `APNS_DEFAULT_BUNDLE_ID` matches mobile app bundle identifier.
|
|
- Avoid coupling route behavior to deployment platform specifics.
|
|
|
|
## Before Finishing
|
|
|
|
- Run `bun run typecheck`.
|
|
- If DB/env behavior changed, run `bun run db:check`.
|
|
- Manually exercise affected endpoints.
|
|
- Confirm logs are useful and secret-safe.
|