{"id":42578003,"url":"https://github.com/localnerve/jam-build-propsdb","last_synced_at":"2026-01-28T22:01:47.031Z","repository":{"id":333399012,"uuid":"1136658139","full_name":"localnerve/jam-build-propsdb","owner":"localnerve","description":"A scalable, observable, high performance drop-in replacement api for the jam-build project","archived":false,"fork":false,"pushed_at":"2026-01-28T02:03:22.000Z","size":12616,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-28T06:28:43.072Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/localnerve.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-18T05:02:17.000Z","updated_at":"2026-01-25T06:20:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/localnerve/jam-build-propsdb","commit_stats":null,"previous_names":["localnerve/jam-build-propsdb"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/localnerve/jam-build-propsdb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localnerve%2Fjam-build-propsdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localnerve%2Fjam-build-propsdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localnerve%2Fjam-build-propsdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localnerve%2Fjam-build-propsdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/localnerve","download_url":"https://codeload.github.com/localnerve/jam-build-propsdb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localnerve%2Fjam-build-propsdb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28853194,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-28T15:15:36.453Z","status":"ssl_error","status_checked_at":"2026-01-28T15:15:13.020Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-28T22:01:46.270Z","updated_at":"2026-01-28T22:01:47.019Z","avatar_url":"https://github.com/localnerve.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# jam-build-propsdb - Go Fiber Data Service\n\nA high-performance data service built with Go and Fiber, serving as a drop-in replacement for the Node.js Express data service in the [Jam Build](https://github.com/localnerve/jam-build) project. Supports all GORM-compatible databases including MariaDB/MySQL, PostgreSQL, SQLite, and SQL Server.\n\n## Features\n\n- 🚀 **High Performance**: Built with Go Fiber for maximum throughput\n- 🗄️ **Multi-Database Support**: Works with MariaDB, MySQL, PostgreSQL, SQLite, and SQL Server via `DB_TYPE` configuration. [Configuration details](docs/DATABASE.md)\n- 🔐 **Authentication**: Integrated with Authorizer using `authorizer-go` SDK\n- 📦 **API Compatibility**: Drop-in replacement for the Node.js Express service. [API details](#api-endpoints)\n- 🔄 **Version Control**: Optimistic locking with `E_VERSION` conflict detection\n- 🐳 **Docker Ready**: Multi-stage Dockerfile for containerized deployments\n- 🧪 **Testable**: Designed for unit, integration, and e2e testing with testcontainers. [Testing details](docs/TESTING.md)\n\n## Quick Start\n\n### Public Docker Image\n\n  * https://hub.docker.com/r/localnerve/jam-build-propsdb\n    - `localnerve/jam-build-propsdb:latest`\n\n  * Environment:\n    - PORT: The exposed port to the propsdb-api\n    - DB_TYPE: The database type [mariadb | mysql | mssql | postgres | sqlite]\n    - DB_HOST: The hostname of the database service\n    - DB_PORT: The database service port\n    - DB_APP_DATABASE: The property database name\n    - DB_APP_USER: The application user name\n    - DB_APP_PASSWORD: The application user password\n    - DB_USER: The user user name\n    - DB_PASSWORD: The user user password\n    - DB_APP_CONNECTION_LIMIT: The application connection pool limit\n    - DB_CONNECTION_LIMIT: The user connection pool limit\n    - AUTHZ_URL: The url to the authorizer service\n    - AUTHZ_CLIENT_ID: The client ID of the authorizer service\n\n### Development\n\n#### Prerequisites\n\n- Go 1.21 or higher\n- Docker Desktop\n- Node 24.12.0 or higher\n- GNU Make 4.4.1\n\n#### Installation\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/localnerve/jam-build-propsdb.git\ncd jam-build-propsdb\n```\n\n2. Install dependencies:\n```bash\nmake deps\nmake install-tools\n```\n\n3. Build and run the full service:\n```bash\nmake docker-compose-up\n```\n\nThe service will start on `http://localhost:3000`.\n\n#### Ports\nThese are the ports used by default:\n\n* Service ports: 3000 (api), 6379 (cache), 8080 (authorizer)\n* Typical database ports (depends on `DB_TYPE`, defaults to `mariadb`):\n    * 3306 (mariadb, mysql)\n    * 5432 (postgres)\n    * 1433 (mssql)\n* Monitoring ports: 3001 (grafana), 9090 (prometheus)\n\n## Database Configuration\n\n### Supported Databases\n\nConfigure the database type using the `DB_TYPE` environment variable (defaults to `mariadb`). For a detailed matrix of configuration requirements (ports, images, healthchecks), see [the database documentation](docs/DATABASE.md).\n\n- **MySQL/MariaDB**: `DB_TYPE=mysql` or `DB_TYPE=mariadb`\n- **PostgreSQL**: `DB_TYPE=postgres` or `DB_TYPE=postgresql`\n- **SQLite**: `DB_TYPE=sqlite` (set `DB_APP_DATABASE` to file path)\n- **SQL Server**: `DB_TYPE=sqlserver` or `DB_TYPE=mssql`\n\n### Initialization\n\nSQL migration files will be applied for each database type in the `data/initdb/` directory:\n\n- `data/initdb/mariadb/` - MariaDB initialization\n- `data/initdb/mysql/` - MySQL initialization\n- `data/initdb/postgres/` - PostgreSQL initialization\n- `data/initdb/sqlite/` - SQLite initialization\n- `data/initdb/sqlserver/` - SQL Server initialization\n\n### Migrations\n\nSQL migration files will be applied for each database type in the `data/migrations/` directory:\n\n- `data/migrations/mariadb/` - MariaDB migrations\n- `data/migrations/mysql/` - MySQL migrations\n- `data/migrations/postgres/` - PostgreSQL migrations\n- `data/migrations/sqlite/` - SQLite migrations\n- `data/migrations/sqlserver/` - SQL Server migrations\n\nThe service also supports GORM AutoMigrate as a fallback.\n\n## API Endpoints\n\nSwagger documentation is available at `http://localhost:3000/swagger/` and updated with `make swagger`.\n\n### Application Data (Public GET, Admin POST/DELETE)\n\n- `GET /api/data/app/:document/:collection` - Get properties for a document/collection\n- `GET /api/data/app/:document?collections=col1,col2` - Get collections and properties\n- `GET /api/data/app` - Get all documents, collections, and properties\n- `POST /api/data/app/:document` - Upsert document (requires admin role)\n- `DELETE /api/data/app/:document/:collection` - Delete collection (requires admin role)\n- `DELETE /api/data/app/:document` - Delete document or properties (requires admin role)\n\n### User Data (All require user authentication)\n\n- `GET /api/data/user/:document/:collection` - Get user properties\n- `GET /api/data/user/:document?collections=col1,col2` - Get user collections\n- `GET /api/data/user` - Get all user documents\n- `POST /api/data/user/:document` - Upsert user document\n- `DELETE /api/data/user/:document/:collection` - Delete user collection\n- `DELETE /api/data/user/:document` - Delete user document or properties\n\n### API Versioning\n\nThe service supports API versioning via the `X-Api-Version` header:\n\n```bash\ncurl -H \"X-Api-Version: 1.0.0\" http://localhost:3000/api/data/app\n```\n\nSupported versions:\n- `1.0.0` (default)\n- `1.0` (alias for 1.0.0)\n\n## Docker Deployment\n\n### Service Stack Docker Compose\n\nThis will start the API service, database, cache, and authorizer.\n\n```bash\nmake docker-compose-up\n```\n\n### Observability Stack Docker Compose\n\nThis will start the observability services for the API service.\n\n```bash\nmake obs-up\n```\n\nFor information on Prometheus metrics and Grafana dashboards, see [OBSERVABILITY](docs/OBSERVABILITY.md).\n\n## Development\n\n### Running Tests\n\nFull information on running tests is available in the [testing documentation](docs/TESTING.md).\n\n```bash\n# Unit tests\nmake test\n\n# Integration tests (requires Docker)\nmake test-integration\n\n# End-to-end service health tests (requires Docker)\nmake test-e2e\n\n# Full stack end-to-end tests (requires Docker)\nmake test-e2e-js # Params: DEBUG=1 (debug, no rebuild), DEBUG=2 (debug, full rebuild)\n\n# Full stack end-to-end tests with coverage (requires Docker)\nmake test-e2e-js-cover # Params: REBUILD=1 (rebuild orchestrator), HOST_DEBUG=1 (debug host)\n\n```\n\nMany more tests are available in the Makefile, see the [testing documentation](docs/TESTING.md) for full details.\n\n### Building\n\n```bash\n# Build the api service binary\nmake build\n\n# Build the healthcheck binary\nmake build-healthcheck\n\n# Build the testcontainers binary\nmake build-testcontainers\n\n# Build the docker image\nmake docker-build\n\n# Build and run the entire composition\nmake DB_TYPE=mariadb docker-compose-up # DB_TYPE = mariadb | mysql | mssql | postgres | sqlite\n\n```\n\n## Authentication\n\nThe service integrates with [Authorizer](https://authorizer.dev/) for authentication and authorization.\n\n- **Admin routes**: Require `admin` role\n- **User routes**: Require `user` role\n- **Session cookie**: `cookie_session`\n\n## Version Control\n\nAll mutation operations (POST, DELETE) use optimistic locking:\n\n1. Client sends current `version` in request body\n2. Server checks if version matches current document version\n3. If mismatch, returns `409 Conflict` with `E_VERSION` error\n4. Client must refresh, reconcile, and retry\n\n## License\n\nCopyright (c) 2026 Alex Grant \u003cinfo@localnerve.com\u003e (https://www.localnerve.com), LocalNerve LLC\n\nThis project is licensed under the GNU Affero General Public License v3.0 or later.\n\n## Acknowledgments\n\nSpecial thanks to the Antigravity AI assistant for help with the Go migration, testing architecture, and documentation.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocalnerve%2Fjam-build-propsdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flocalnerve%2Fjam-build-propsdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocalnerve%2Fjam-build-propsdb/lists"}