94 lines
4.3 KiB
Markdown
94 lines
4.3 KiB
Markdown
|
# restxlsx — Task Progress & Decisions
|
||
|
|
|
||
|
|
## Architecture Decisions
|
||
|
|
|
||
|
|
| Decision | Choice | Rationale |
|
||
|
|
|---|---|---|
|
||
|
|
| Language | Go 1.24 | Cross-platform, single-binary, great HTTP/stdlib |
|
||
|
|
| Excel parsing | `excelize/v2` | The de-facto Go xlsx library, full read/write support |
|
||
|
|
| HTTP router | `go-chi/chi/v5` | Lightweight, idiomatic, stdlib-compatible, middleware-friendly |
|
||
|
|
| GraphQL | `graphql-go/graphql` | Pure Go, no code-gen, dynamic schema from data |
|
||
|
|
| OpenAPI generation | Manual struct-to-spec | Schema is dynamic (based on xlsx tables), no code-gen tool fits |
|
||
|
|
| Swagger UI | Embedded static files | Serves swagger-ui in debug mode via `embed` |
|
||
|
|
| Logging | `log/slog` (stdlib) | Structured logging, no deps, configurable levels |
|
||
|
|
| Config | `flag` + env vars | Zero-dependency, clean; flags override env vars override defaults |
|
||
|
|
| ID field | First column of each table | Simple convention; assumed to be unique |
|
||
|
|
| Data storage | In-memory (read from xlsx at startup) | No external DB needed; lightweight proxy to the file |
|
||
|
|
| GraphQL schema | Dynamic per-table | Generated at startup from the xlsx table structure |
|
||
|
|
| xlsx generation | Python + openpyxl | Best Python library for creating rich xlsx files |
|
||
|
|
|
||
|
|
## Completed Tasks
|
||
|
|
|
||
|
|
- [x] Plan architecture & create tasks.md
|
||
|
|
- [x] Generate sample xlsx file with tables (Employees, Products, Orders)
|
||
|
|
- [x] Initialize Go module & install dependencies (chi, excelize, graphql-go)
|
||
|
|
- [x] Implement configuration (CLI flags + env vars: --file, --port, --debug, --quiet, --log-reads, --log-file)
|
||
|
|
- [x] Implement logging (stdout via slog, --quiet suppresses, RESTXLSX_LOG_READS=false skips reads)
|
||
|
|
- [x] Implement Excel file parsing engine (open, list tables, read/write rows, flush to disk)
|
||
|
|
- [x] Implement RESTful CRUD API endpoints (GET/POST/PUT/DELETE per table)
|
||
|
|
- [x] Implement GraphQL endpoint (dynamic Query type with get_/list_/create_ per table)
|
||
|
|
- [x] Implement dynamic OpenAPI spec + Swagger UI (/openapi.json, /swagger in debug mode)
|
||
|
|
- [x] Wire everything in main.go (chi router, graceful shutdown, signal handling)
|
||
|
|
- [x] Build and test the service (all endpoints verified with curl)
|
||
|
|
- [x] Create multi-stage Dockerfile (scratch image, 8080 exposed)
|
||
|
|
- [x] Add auth middleware with admin/writer/reader roles
|
||
|
|
- [x] Change default host to localhost:3000, add --host flag
|
||
|
|
- [x] Add /api/sql endpoint (basic SQL query translation)
|
||
|
|
- [x] Add /api/ddl/* endpoints (create/drop tables and sheets)
|
||
|
|
- [x] Add JSON Content-Type middleware
|
||
|
|
- [x] Wire auth into all endpoints (REST, GraphQL, SQL, DDL)
|
||
|
|
- [x] Change default auth from admin to writer
|
||
|
|
- [x] Create comprehensive README.md with configuration docs
|
||
|
|
|
||
|
|
## Log
|
||
|
|
|
||
|
|
### 2026-06-10 Initial Build
|
||
|
|
- Created full Go project from scratch
|
||
|
|
- Used Python/openpyxl to generate sample.xlsx with 3 tables
|
||
|
|
- All deps: chi v5.3.0, excelize v2.10.1, graphql-go v0.8.1
|
||
|
|
- REST API, GraphQL, OpenAPI, Swagger UI all verified working
|
||
|
|
- Config via flags/env vars with sensible defaults
|
||
|
|
- Graceful shutdown on SIGINT/SIGTERM
|
||
|
|
- Multi-stage Dockerfile included
|
||
|
|
|
||
|
|
### 2026-06-10 Auth, SQL, DDL, README
|
||
|
|
- Added `--auth` flag (admin/writer/reader) with middleware enforcement
|
||
|
|
- Changed default port to 3000, added `--host` flag (default localhost)
|
||
|
|
- Added `POST /api/sql` endpoint with minimal SQL parser (SELECT, INSERT, UPDATE, DELETE)
|
||
|
|
- Added DDL endpoints under `/api/ddl/` for create/drop sheets and tables
|
||
|
|
- Added JSON Content-Type middleware for consistent API responses
|
||
|
|
- Changed default auth role from admin to writer
|
||
|
|
- Enhanced OpenAPI spec with SQL and DDL endpoints, server URL fix
|
||
|
|
- Created comprehensive README.md with config tables, auth docs, OIDC integration path
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Run directly
|
||
|
|
./restxlsx --file data/sample.xlsx --port 8080
|
||
|
|
|
||
|
|
# With debug mode (enables /openapi.json and /swagger)
|
||
|
|
./restxlsx --debug
|
||
|
|
|
||
|
|
# Quiet mode (no stdout)
|
||
|
|
./restxlsx --quiet
|
||
|
|
|
||
|
|
# Or via env vars
|
||
|
|
RESTXLSX_FILE=data/sample.xlsx RESTXLSX_DEBUG=true ./restxlsx
|
||
|
|
```
|
||
|
|
|
||
|
|
## Endpoints
|
||
|
|
|
||
|
|
| Method | Path | Description |
|
||
|
|
|---|---|---|
|
||
|
|
| GET | /health | Health check |
|
||
|
|
| GET | /api/tables | List discovered tables |
|
||
|
|
| GET | /api/{table} | List records |
|
||
|
|
| POST | /api/{table} | Create record |
|
||
|
|
| GET | /api/{table}/{id} | Get record |
|
||
|
|
| PUT | /api/{table}/{id} | Update record |
|
||
|
|
| DELETE | /api/{table}/{id} | Delete record |
|
||
|
|
| POST | /graphql | GraphQL query |
|
||
|
|
| GET | /openapi.json | OpenAPI spec (debug only) |
|
||
|
|
| GET | /swagger | Swagger UI (debug only) |
|