From 460c2ed90a24d929dc89c6337d6c0e4bb7494883 Mon Sep 17 00:00:00 2001 From: Vladimir Svacko Date: Wed, 28 Jan 2026 14:15:28 +0100 Subject: [PATCH] feat: preparation for README recreation --- AGENTS.md | 124 +++++++++++++++++++++++++++++++++++++ NOTES.md | 14 +++++ README.md => README_old.md | 4 +- 3 files changed, 140 insertions(+), 2 deletions(-) create mode 100644 AGENTS.md create mode 100644 NOTES.md rename README.md => README_old.md (99%) diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..916a811 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,124 @@ +# Zabbix GraphQL API - AI Coding Instructions + +## Project Overview +This is a **GraphQL wrapper for Zabbix API** that provides enhanced mass import/export operations, hierarchical host group management, and dynamic schema extensibility. It's built with **Apollo Server**, TypeScript, and uses ES modules throughout. + +## Architecture & Key Patterns + +### Core Components +- **Entry Point**: `src/index.ts` → `src/api/start.ts` (Apollo Server setup) +- **Schema Loading**: `src/api/schema.ts` - Dynamic schema merging with extensibility via env vars +- **Resolvers**: `src/api/resolvers.ts` + dynamic hierarchical resolvers via `resolver_helpers.ts` +- **DataSources**: `src/datasources/` - Zabbix API wrappers extending `RESTDataSource` +- **Execution**: `src/execution/` - Complex business logic (importers, deleters) + +### Critical Patterns + +#### 1. Hierarchical Data Mapping +The core innovation is **automatic mapping** of Zabbix items/tags to GraphQL nested objects: +- Zabbix item key `state.current.values.temperature` → GraphQL `{ state: { current: { values: { temperature } } } }` +- Use `createHierarchicalValueFieldResolver()` in `resolver_helpers.ts` +- Type hints: `json_`, `str_`, `bool_`, `float_` prefixes for value conversion + +#### 2. Dynamic Schema Extension (No-Code) +Configure via environment variables: +```bash +ADDITIONAL_SCHEMAS=./schema/extensions/display_devices.graphql,./schema/extensions/location_tracker_devices.graphql +ADDITIONAL_RESOLVERS=SinglePanelDevice,FourPanelDevice,DistanceTrackerDevice +``` +Schema loads dynamically in `schema.ts`, resolvers auto-generated for listed types. + +#### 3. Mass Import/Export Pattern +All importers follow hierarchy-first approach: +- **Host Groups**: Process parent groups before children (`getHostGroupHierarchyNames()`) +- **Template Dependencies**: Handle dependent items via deferred creation logic +- **Batch Processing**: Each importer returns array of `Response` objects with success/error details + +#### 4. Permission System +Uses Zabbix template groups as permission containers: +- Template groups with prefix `Permissions/` (configurable via `ZABBIX_PERMISSION_TEMPLATE_GROUP_NAME_PREFIX`) +- Queries: `hasPermissions()`, `userPermissions()` in resolvers +- Integration: `ZabbixRequestWithPermissions` wrapper class + +## Development Workflow + +### Essential Commands +```bash +# Development with hot reload +npm run start + +# Production build & run +npm run compile && npm run prod + +# GraphQL code generation (watch mode) +npm run codegen + +# Testing (with ES modules + mocking setup) +npm test +``` + +### Environment Setup +Key variables (see README for complete list): +```bash +ZABBIX_BASE_URL=http://zabbix.example.com/zabbix +ZABBIX_AUTH_TOKEN=your-super-admin-token +ZABBIX_EDGE_DEVICE_BASE_GROUP=Roadwork +SCHEMA_PATH=./schema/ +``` + +### Testing Patterns +- **ES Module Mocking**: Uses `jest.mock()` with proper module resolution +- **API Mocking**: Mock `zabbixAPI.executeRequest()` and `zabbixAPI.post()` +- **Permission Bypass**: Mock `ZabbixRequestWithPermissions` for unit tests +- **Integration Tests**: Use real GraphQL queries against mocked Zabbix responses + +## File Organization & Conventions + +### Schema Files (`schema/`) +- `queries.graphql`, `mutations.graphql` - Main API surface +- `devices.graphql`, `zabbix.graphql` - Core types +- `extensions/` - Custom device types for schema extension + +### DataSource Naming +- Pattern: `zabbix-{entity}.ts` (e.g., `zabbix-hosts.ts`, `zabbix-templates.ts`) +- Each exports specialized request classes extending `ZabbixRequest` +- Helper classes: `{Entity}Helper` for common operations + +### Generated Code +- `src/schema/generated/graphql.ts` - Auto-generated from schema via GraphQL Code Generator +- Enum values imported from `src/model/model_enum_values.ts` +- **Never edit generated files directly** + +### Import Statements +**Always use `.js` extensions** in imports due to ES modules: +```typescript +import {logger} from "../logging/logger.js"; // ✅ Correct +import {logger} from "../logging/logger"; // ❌ Will fail +``` + +## Debugging & Extensions + +### Adding New Device Types +1. Create schema in `schema/extensions/{name}.graphql` +2. Add to `ADDITIONAL_SCHEMAS` env var +3. Add type name to `ADDITIONAL_RESOLVERS` env var +4. Ensure Zabbix items use dot-separated keys matching GraphQL field names + +### Common Issues +- **Module Resolution**: Check `.js` extensions in imports +- **Permission Errors**: Verify `ZABBIX_AUTH_TOKEN` has Super Admin rights +- **Schema Changes**: Run `npm run codegen` after modifying `.graphql` files +- **Hierarchical Mapping**: Debug via `createHierarchicalValueFieldResolver()` logs + +### Integration Points +- **Zabbix API**: All requests go through `ZabbixAPI` class (extends `RESTDataSource`) +- **Authentication**: Supports both API tokens and session cookies +- **WebSocket**: GraphQL subscriptions enabled via `graphql-ws` +- **Docker**: Multi-stage build with `API_VERSION` build arg + +## Testing Strategy +Focus on: +1. **Unit Tests**: Mock Zabbix API responses, test business logic +2. **Integration Tests**: Real GraphQL operations with mocked datasources +3. **Permission Tests**: Verify access control logic +4. **Import/Export Tests**: Test hierarchical processing and error handling \ No newline at end of file diff --git a/NOTES.md b/NOTES.md new file mode 100644 index 0000000..1464404 --- /dev/null +++ b/NOTES.md @@ -0,0 +1,14 @@ +local auth token: 47d92d4c88ed2ac842357e342e8da9c1f272f4ca0d046d1d6a615a5f7a6b1ab2 + +alt: 9228fc973883eeb5cab421d5b7ecefeb + + +## Notizen: +- Get Hosts/Hostgroups funktioniert nicht nativ. Custom Group stört +- TODO: Mutation test +- TODO: Erweiterung test und Anleitung +- Übersicht weche zabbix-api funktionen Abgedeckt sind und welche nicht. gg.f mit einem todo versehen um zu sugerieren, dass es kommen könnte +- + +- Devices und Hosts nicht hinreichend erklärt im Kontext allDevices +- Integrated management of user roles and user groups.: aber keiner queries zu Roles und groups, hier explizit auf extension hinweisen diff --git a/README.md b/README_old.md similarity index 99% rename from README.md rename to README_old.md index 71b50a7..ea8e536 100644 --- a/README.md +++ b/README_old.md @@ -77,7 +77,7 @@ npm run prod The API will be available at `http://localhost:4000/`. -## Running with Docker +#### Running with Docker ### Using the Pre-built Image @@ -98,7 +98,7 @@ docker run -d \ forgejo.tooling.hilbigit.com/zabbix/zabbix-graphql-api:latest ``` -### Building Locally +#### Building Locally If you prefer to build the image yourself using the provided `Dockerfile`: