go-duck-cli

v1.5.52

Published

3 days ago

The Ultimate Evolutionary Go Microservice Scaffolder.

0High
0Medium
0Low

trish-v

go golang microservice scaffold cli generator backend heavenscode go-duck

GO-DUCK CLI

🦆 The Legend of the Century

Watch the intro video

In the legendary Silicon Valley of Code, a nomadic Gopher—lightning-fast and known for his tireless concurrency—crossed paths with a Duck from the Great Persistence Bayou. The Duck held the wisdom of adaptability and the secret to navigating ever-shifting business tides. They realized that while the Gopher built fast, the Duck built to survive. Together, they forged a pact to create the Generator of Kings.

Gin Gonic Tonic: The Refreshment of Performance

To fuel their grand design, they sought the Legendary Bottle of Gin. This magical brew wasn't just for hydration; it transformed their web routing into a crystalline, high-performance flow. Routes became fast, middleware became transparent, and the developer experience became as refreshing as a cold tonic on a summer's day. This gave GO-DUCK its distinctive, lightweight spirit.

The Armor of the Divine: Mark of Kratos

But speed without strength is a house made of cards. In the digital forge of the underworld, they recovered the Mark of Kratos. By stamping this sigil onto their internal services, they achieved gRPC industrial resilience. Every service became armored with strict Protocol Buffer contracts, ensuring that no matter how hard the system scaled, it would never break under the divine weight of technical debt.

The GDL Genesis

Thus, the GDL (Go-Duck Language) was hatched. A single, simple tongue that could command entire legions of code. From that day forth, every developer who whispered GDL into the CLI would see their architecture evolve—bringing the Gopher's speed, the Duck's wisdom, the Gin's clarity, and the Kratos' strength into a single, unified masterpiece.

🦆 The 495% Elite Status: Milestone Surpassed

GO-DUCK has officially reached the 495% Achievement Status, evolving from a code generator into a High-Velocity Distributed Orchestrator. This elite status confirms that the framework has surpassed the original 350% milestone with industrial-grade Universal Storage extensions, real-time remote bootstrapping, WSO2 integration, full-spectrum GDL evolution, and the new Hybrid Elasticsearch & JPA Meta-Filtering engines.

🦆 Milestone Achievement: ManyToMany Relationships & Dynamic Swagger Prefixes (2026-06-10) ✅

The core generation engine was upgraded to support complex many-to-many relationship mapping and runtime dynamic Swagger OpenAPI configurations, bringing GO-DUCK to 495% Elite Status.

Implementation Highlights:

Native ManyToMany GDL Engine: Added complete parsing support for ManyToMany relationships in GDL, scaffolding GORM many2many join table metadata, generating standard GORM schemas, list representations in GraphQL resolver graphs, and dynamic Goose database migrations.
Dynamic Runtime Swagger Prefix Resolution: Replaced static OpenAPI file serving with a live Go-native handler (serveDynamicSwagger) that dynamically inspects runtime config (api-path-prefix) in dev vs prod, rewriting path definitions in the OpenAPI schema on the fly and adapting the interactive Swagger UI spec URL.
On-Demand Tenant Silo Migrations: Fortified multi-db multitenancy connection pooling by automatically executing Goose SQL migrations on dynamic tenant databases inside GetDB upon initialization, preventing missing relation errors (e.g., harbour does not exist) in dynamic silos.
GDL Default Parsing Regex Boundary Fix: Corrected the parsing regex for default constraints to enforce word boundaries (\bdefault\b), resolving compilation errors when entities contained standard field prefix names such as defaultConfig.

🦆 Milestone Achievement: Performance & Developer Experience Upgrades (2026-06-03) ✅

The core generation engine received critical optimizations targeting API Time-To-First-Byte (TTFB) and Swagger UI usability, further solidifying the Elite Status.

Implementation Highlights:

Asynchronous Cache Invalidation: Completely eliminated O(N) synchronous Redis blocking during CRUD operations by offloading cache.ClearPattern execution to goroutines.
Bulk Federated Outbox Dispatch: Refactored the Federated Parallel Harvester write-path to use lightning-fast GORM Bulk Inserts (tx.Create(&outboxes)) instead of iterative N+1 network calls per isolated silo.
@ActiveStatus Annotation Support: CLI seamlessly defaults IsActive fields to true upon entity creation without breaking zero-value semantics, cleanly separating creation state from PATCH deactivations.
Swagger UX Enhancements: Injected the custom CaseInsensitiveFilterPlugin into the Swagger UI layout to enable case-agnostic API searching, and upgraded the default interactive MQTT WebSocket strings to properly resolve /mqtt.
Wildcard MQTT Subscriptions: Refactored the interactive MQTT dictionary topics from literal entity paths to multi-tenant wildcard topics (+/Entity/ACTION).

🦆 Milestone Achievement: Cloud-Native K8s & Defaults (2026-06-04) ✅

The Kubernetes engine received a massive 12-factor cloud-native overhaul, and the GDL language was expanded to support explicit default values.

Implementation Highlights:

Cloud-Native Kubernetes Definitions: Transitioned app.yaml to dynamically dump configurations into mounted ConfigMap volumes, removing bulky environment variables.
Zero-Trust K8s Secrets: Passwords and Keycloak client secrets are now strictly isolated in Opaque Kubernetes Secrets and injected via secretKeyRef.
Horizontal Pod Autoscaling (HPA): Kubernetes container resources (Requests/Limits) and native autoscaling/v2 HPA manifests are scaffolded by default to handle elastic load spikes.
GDL Default Values: The syntax now supports default=<value> on Strings, Numerics, Booleans, and Enums, injecting SQL DEFAULT constraints and dynamically stripping binding:"required" to allow omittable API JSON payloads.

🦆 Milestone Achievement: Elite Multitenancy & Swagger Polish (2026-06-26) ✅

The multi-tenancy and CLI automation engines received a targeted hardening, elevating developer experience and multi-silo stability.

Implementation Highlights:

Admin Tenant Impersonation & Fallback Fix: Rewrote the tenant_middleware multitenancy logic. Keycloak users with admin or ROLE_SUPER_ADMIN roles are no longer erroneously forced onto the master fallback database. Super Admins can now effortlessly impersonate specific tenants by passing the X-Tenant-ID header while preserving standard role mappings.
Deep Artifact Purging for @Delete: Upgraded the CLI dead-code purger to track and delete legacy Kratos gRPC api/v1/*.proto and internal/service/*.go artifacts when an entity is purged via the @Delete annotation.
Dynamic Swagger Conditional Rendering: Fortified the Swagger UI generator to conditionally hide Storage API endpoints if no Object Storage providers (S3/MinIO/SFTP) are enabled in the active configuration.
Unlimited Quota SaaS Metering: Enhanced the distributed Redis metering engine to recognize -1 as an unlimited tier, effectively bypassing 402 Payment Required blocks for internal super-users.

✨ Primary Features (The 495% Core)

Federated Multi-Tenancy: Side-by-side Database-per-Tenant isolation with a Master-Tenant Registry (Role ↔ DB ↔ Opaque UUID).
Multi-Protocol REST: Dynamically switchable REST rendering using standard json or high-performance messagepack based on configuration.
gRPC-Web Native Proxy: Natively wraps Kratos gRPC to automatically serve a web proxy (e.g. on port 9090) to allow direct frontend Protobuf interaction.
Industrial-Grade Parallel Harvester: Asynchronous goroutine-based data aggregation across multiple silos with ?federated=true opt-in.
Precision Harvesting: Surgical multi-silo selection via comma-separated X-Tenant-ID headers.
Super Admin Security Boundaries: Strict architectural separation between Business APIs and Infrastructure Control APIs.
Serverless Transformation: Opt-in AWS Lambda native adapter (via config.yaml) with build-tag native entry points for on-demand cloud scaling.
Generic Search Layer: PostgREST-like RPC endpoint (/api/rpc/:table) with Deep JSON/JSONB Querying using arrow operators (->, ->>).
Distributed Saga Consistency: Integrated Transactional Outbox pattern and background workers in every silo to guarantee eventual consistency across the federation.
Zero-Trust Identity Registry: Decoupled mapping layer ensuring physical database names and internal IDs never leak to the client.
Universal Storage Mesh: Dynamic Multi-Provider Registry allowing hot-swapping at runtime via ?provider= queries, alongside Distributed Cross-Scan endpoints to auto-locate files across AWS, GCS, SFTP, and GitHub lakes.
Enterprise API Gateway Compatibility: Natively exposes the Swagger/OpenAPI JSON specification at /v3/api-docs to ensure drop-in compatibility with JHipster, WSO2 API Manager, and Spring Boot ecosystems.
Dual Retrieval APIs: Every generated entity now intelligently separates traffic with two dedicated GET endpoints: a lightning-fast /api/{entity} endpoint for strict flat JPA-style meta-filtering, and an optimized /api/{entity}/eager endpoint tailored for relational dynamic joins and nested data loading.
Dynamic Join Engine: A powerful feature allowing on-the-fly M:N relational joins via REST (GET /api/{entity}/join/{targetTable}?onA=id&onB=foreign_id). Engineered with an Anti-IDOR Strict Entity Whitelist to completely block unauthorized table querying, and hardened with mandatory Pre-Join Pagination Controls to prevent unbounded SQL IN array injections and protect the Go microservice from Out-of-Memory (OOM) crashes.
Next-Gen Swagger UI: A fully glassmorphism-styled Swagger UI with seamless Keycloak SSO integration. Features automatic JWT token refresh, dynamic X-Tenant-ID header injection, and CLI metadata branding. The generated documentation explicitly models the Dual Retrieval APIs, showcasing the standard filter routes alongside the dynamic join /eager routes. Now features a Live Interactive MQTT Dictionary, allowing users to instantly subscribe or publish payloads directly from the docs via WebSockets!
JPA-Style Dynamic Meta Filters: Extends standard REST retrieval logic with strict JPA/JHipster-style operator filtering. Appending operators to fields dynamically translates them into their respective backend equivalents (ILIKE for PostgreSQL, $regex for MongoDB). Includes support for: .equals, .notEquals, .greaterThan, .lessThan, .contains, .in, and more.
Elasticsearch Hybrid Engine: High-performance full-text search engine. Entities marked with @Searchable are automatically synced to Elasticsearch in real-time. The engine natively fuses raw Lucene Query Syntax strings seamlessly alongside strict JPA-Style Meta Filters, translating everything into secure, optimized bool queries with X-Total-Count header parity.
SaaS Quota Engine: Redis-backed API bandwidth tracking with dynamic, hierarchical limits (User vs. Role mapping).
Resilience Layer: Sony/Gobreaker Integration + Zero-Trust Distributed Redis Rate Limiter.
Comprehensive GDL Schema Evolution: Detects structural deltas intelligently and automatically generates Goose SQL for dropped entities (DROP TABLE), dropped fields (DROP COLUMN), and altered fields (ALTER TYPE, constraints) to keep databases in absolute sync.
Entity Archiving: Apply the @ArchiveStatus annotation or archived * global declaration to instantly inject an archived boolean field across the PostgreSQL, MongoDB, and Go layers.
Dead-Code Purging: Automatically cleans up orphaned Go models and controllers when removing entities from the .gdl blueprint.
Saga Outbox GORM Stability: Generates robust, compile-ready outbox_worker.go components with native GORM package resolution.

🗺️ System Topology & Identity Registry

To prevent ID enumeration attacks and completely hide internal database names and structure, GO-DUCK implements a zero-trust Triple-Identity Registry (Role ↔ DB ↔ Opaque UUID):

💾 Global Installation

To get started with GO-DUCK CLI, install it globally via npm:

npm install -g go-duck-cli

Environment Specifications

Ensure your development environment meets the following requirements:

Node.js: 18+
Go: 1.21+
Docker: v20+
Composability: v2+

🧱 GDL Data Types & Modifiers

The GO-DUCK schema parser (parser/gdl.js) supports a robust set of data types and modifiers, seamlessly translating them into native Go types and PostgreSQL/Liquibase equivalents.

Data Types

Field Modifiers (Validators)

Modifiers can be appended directly to the end of any field definition in your .gdl file.

Example Usage in .gdl:

entity Product {
    String(100) name required unique
    BigDecimal price default=0.00
    Text description
    Boolean isActive default=TRUE
    ArticleStatus status default=DRAFT
    tags List(String)
    history [String]
}

Quick‑Start

Follow these four steps to get a generated microservice running locally and in Kubernetes:

Create: go-duck create -o ./my-app -c config.yaml
Enter: cd my-app
Build & Push: ./push.sh my-registry/my-app:1.0.0
Deploy: kubectl apply -f devops/k8s/

🚀 Scaffold & Run

Follow these steps to create and run a new microservice with GO-DUCK:

# 0. Design your schema visually (Optional)
go-duck gdl-planner -p 8000

This launches a browser-based drag-and-drop canvas at http://localhost:8000 where you can visually design your entities, relationships, nested BSON objects, and Enums, and then export it directly into a .gdl file!

# 1. Create a new microservice
go-duck create -o ./my-app -c config.yaml

# 2. Enter the application directory
cd my-app

# 3. Build, tag, and push Docker image (updates app.yaml)
./push.sh my-registry/my-app:1.0.0

# 4. Deploy to Kubernetes
kubectl apply -f devops/k8s/

### 🚢 Deploy to Kubernetes & Push Images

The generated project includes a **devops/k8s** directory with ready‑to‑apply Kubernetes manifests:

- `mongo.yaml` – StatefulSet & Service for MongoDB.
- `minio.yaml` – Deployment & Service for MinIO object storage.
- `app.yaml` – Deployment for the generated Go microservice, referencing a placeholder image name (`<app‑name>:latest`). Replace the image with the tag you push.

A helper script **push.sh** (located at the project root) automates the Docker build, tag, push, and then updates the `app.yaml` image field:

```bash
./push.sh my-registry/my-app:1.0.0

After pushing, deploy everything with:

kubectl apply -f devops/k8s/

[!NOTE] The K8s manifests use placeholder values (e.g., resource limits, storage class). Adjust them to match your cluster requirements before applying.


### 🏗️ Compiling Protobuf & gRPC Contracts

Before running the microservice, compile the protobuf contract files using the scaffolded scripts:

> [!NOTE]
> **Do I need to run this?**
> *   **Yes (Local Host Execution)**: You must run the compilation script whenever you first create the microservice, or whenever you modify the GDL schemas and re-run `import-gdl` to generate updated gRPC structures.
> *   **No (Docker Deployment)**: If you compile and run the application via Docker (using `docker build` or `docker-compose`), the multi-stage `devops/Dockerfile` compiles the protobuf definitions internally, so you do not need to run the scripts locally.

#### Prerequisites
1. Ensure the `protoc` compiler is installed and added to your system's `PATH`.
2. Install the necessary Go compiler plugins:
   ```cmd
   go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
   go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

Compilation

Execute the script corresponding to your operating system in the root of the generated microservice directory:

Windows CMD / PowerShell:
```
.\generate.bat
```
Linux / macOS / Git Bash / WSL:
```
chmod +x generate.sh
./generate.sh
```

Once compiled, launch the dependencies and start the application:

# 3. Spin up dependent services
docker-compose up -d

# 4. Run the Go application
go run main.go

🌐 Calling the Multi-Protocol Endpoints

GO-DUCK automatically exposes your microservice across three distinct ports to serve different architectural needs without code duplication:

REST API (Port 8080 by default) Standard HTTP endpoints for web browsers and legacy clients.
- JSON (Default): Perfect for general use.
- MessagePack (High Performance): To switch to binary MessagePack, update your config.yaml before generation:
```
server:
  rest:
    port: 8080
    protocol: "messagepack"
```
  Clients must send the Accept: application/msgpack and Content-Type: application/msgpack headers to consume this endpoint correctly.
- Pagination & Sorting: All GetAll endpoints support pagination via ?page=1&size=20, and dynamic sorting via ?sort=field,asc or ?sort=field,desc (e.g. ?sort=name,desc).
Native Kratos gRPC (Port 9000 by default) Pure HTTP/2 Protobuf communication. Used strictly for internal backend-to-backend communication (e.g., Microservice A calling Microservice B) where maximum throughput is required.
gRPC-Web Proxy (Port 9090 by default) Web browsers cannot speak raw HTTP/2 gRPC. This port acts as an HTTP/1.1 proxy bridge, allowing frontend frameworks (React, Angular, Vue) to interact directly with the Protobuf gRPC contracts. To disable or change the proxy port, update your config.yaml:
```
server:
  grpc:
    web_enabled: true
    web_port: 9090
```
Frontend Tip: Use the grpc-web npm package to generate a frontend client that communicates with this port!

📊 Telemetry & Observability

GO-DUCK automatically integrates industrial observability stack:

OpenTelemetry Distributed Tracing: Native otelgin and gorm.io/plugin/opentelemetry/tracing integrations.
Triple-Metrics Endpoints:
- GET /metrics: Standard Prometheus scraping endpoint for Kubernetes Horizontal Pod Autoscaling (HPA).
- GET /api/system/stream: A Server-Sent Events (SSE) endpoint streaming live JSON payloads of CPU, Memory, and Load Percentages directly to your browser for real-time dashboards.
- GET /api/system/metrics: A massive JSON endpoint returning JHipster-style metrics (Go GC pauses, Uptime, Goroutines, exact endpoint hits, latencies, and failed calls).
Datadog Logging: Environment-driven log streaming and monitoring natively via logger package.

Usage

The go-duck-cli has two main commands: create and import-gdl.

`go-duck create`

This command scaffolds a new Go microservice.

go-duck create [options]

Options:

-c, --config <path>: Path to the config.yaml file (default: ../CONFIG/config.yaml).
-o, --output <path>: Path where the project will be generated (default: current directory).
-g, --gdl <path>: Path to the directory containing your GDL files (default: ../GDL).

Example:

go-duck create -c my-app/config.yaml -o my-app -g my-app/gdl

`go-duck import-gdl <file>`

This command imports a GDL file to an existing project, generating new entities, updating existing ones, and creating database migrations.

go-duck import-gdl <file> [options]

Options:

-o, --output <path>: Path to the existing application root (default: current directory).
--preserve-root: Protects top-level configurations. When active, it skips regenerating main.go, push.sh, and the devops/ folder, preserving your custom root-level logic while continuing to safely generate models, controllers, and schemas.

Example:

go-duck import-gdl new-entities.gdl -o my-existing-app --preserve-root

GoDuck Definition Language (GDL)

GDL is a clean DSL for defining your application's entities, enums, fields, nested document structures, relationships, and public/auth boundaries.

Example (app.gdl):

// ==============================================================================
// 🦆 GO-DUCK ELITE DEALERSHIP BLUEPRINT
// ==============================================================================

/**
 * Car: Relational Entity stored in PostgreSQL.
 * @Searchable: Enable Spring-style fuzzy search on make/model.
 * @Federated: Synchronize history across all dealership siloes.
 * @Audited: Track every modification with Zero-Trust Keycloak IDs.
 */
@Searchable @Federated @Audited
entity Car {
    string(100) make     required
    string(100) model    required
    int(32)     year     required
    bigdecimal  price
    string(50)  vin      unique
    jsonb       metadata
}

/**
 * Patient: MongoDB Document Entity.
 * @Document: Stored in MongoDB instead of PostgreSQL.
 */
@Document
entity Patient {
    string name required
    clinicalData {
        vitals {
            int bpm
            float temp
        }
        history [String]
    }
}

/**
 * ArticleStatus: Native Enum Support.
 * GO-DUCK generates Go Enums, GraphQL Enums, and Proto definitions.
 */
enum ArticleStatus {
    DRAFT, PUBLISHED, ARCHIVED
}

// 🦆 RELATIONSHIPS: Build the Graph
relationship OneToMany {
    Customer{car} to Car{owner}
}

// 🦆 SECURITY: Define Public/Auth Access
open Car(read)

Configuration (`config.yaml`)

The config.yaml file configures the scaffolding engine and generated Go bootstrap files. It must start with the top-level go-duck block.

go-duck:
  name: "my-app"
  version: "1.0.0"
  description: "GO-DUCK Scaffolded Microservice"
  
  # --- Network & Server Layer ---
  server:
    port: 8080
    grpc:
      addr: ":9000"
      network: "tcp"
      timeout: "1s"
    cors:
      allow-origins: ["*"]
      allow-methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]
      allow-headers: ["Origin", "Content-Type", "Accept", "Authorization", "X-Tenant-ID"]
      
  # --- Persistence Layer (Hybrid Store) ---
  datasource:
    # PostgreSQL (Relational Registry & Entity Store)
    host: "localhost"
    port: 5432
    username: "postgres"
    password: "password"
    database: "my_app_db"
    ssl-mode: "disable"
    # MongoDB (Document Entity Store)
    mongodb:
      enabled: true
      uri: "mongodb://localhost:27017"
      database: "my_app_mongo"
      
  # --- Security & Identity (Keycloak/OIDC) ---
  security:
    keycloak-host: "http://localhost:8080"
    keycloak-realm: "my-realm"
    keycloak-app-client-id: "my-app"
    keycloak-service-client-id: "my-service"
    keycloak-service-secret: "service-secret-123"
    super-admin-role: "admin"
    confidential-mode: true
    rate-limit:
      rps: 100
      burst: 200

  # --- Telemetry & Metrics ---
  telemetry:
    otel:
      enabled: true
      endpoint: "localhost:4317"
    metrics:
      prometheus-enabled: true
      stream-enabled: true
      stream-interval: "1s"

  # --- Federated Multi-Tenancy ---
  multitenancy:
    enabled: true
    hide-silo-names: false

License

This project is licensed under the ISC License.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

GO-DUCK CLI

🦆 The Legend of the Century

Gin Gonic Tonic: The Refreshment of Performance

The Armor of the Divine: Mark of Kratos

The GDL Genesis

🦆 The 495% Elite Status: Milestone Surpassed

🦆 Milestone Achievement: ManyToMany Relationships & Dynamic Swagger Prefixes (2026-06-10) ✅

Implementation Highlights:

🦆 Milestone Achievement: Performance & Developer Experience Upgrades (2026-06-03) ✅

Implementation Highlights:

🦆 Milestone Achievement: Cloud-Native K8s & Defaults (2026-06-04) ✅

Implementation Highlights:

🦆 Milestone Achievement: Elite Multitenancy & Swagger Polish (2026-06-26) ✅

Implementation Highlights:

✨ Primary Features (The 495% Core)

🗺️ System Topology & Identity Registry

💾 Global Installation

Environment Specifications

🧱 GDL Data Types & Modifiers

Data Types

Field Modifiers (Validators)

Quick‑Start

🚀 Scaffold & Run

Compilation

🌐 Calling the Multi-Protocol Endpoints

📊 Telemetry & Observability

Usage

go-duck create

go-duck import-gdl <file>

GoDuck Definition Language (GDL)

Configuration (config.yaml)

License

`go-duck create`

`go-duck import-gdl <file>`

Configuration (`config.yaml`)