v1.0.0-alpha2 — Catamaran

Naftiko Framework v1.0.0-alpha2 — "Catamaran" 🚢 — Release Notes

🚀 The second Alpha sets sail! This release expands Naftiko with inline scripting, OpenAPI interoperability, distributed tracing, a control port, OAuth 2.1 server auth, and DDD-inspired aggregates — moving the framework closer to a complete spec-driven integration engine.

What is the Naftiko Framework?

The Naftiko Framework is an open-source Java runtime that lets you declare, compose, and expose API capabilities — from simple HTTP proxies to AI-ready MCP tools — using a declarative, specification-driven approach.

This v1.0.0-alpha2 release builds on v1.0.0-alpha1 with a focus on programmability, observability, security, and interoperability. The engine now supports inline scripting, OpenTelemetry-based tracing and metrics, a runtime control port, OAuth 2.1 server authentication, OpenAPI import/export, and DDD-inspired aggregates.

✨ Highlights

🔀 OpenAPI Interoperability

Import and export capabilities to/from the OpenAPI ecosystem:

• OAS Import — convert OpenAPI 3.0 and 3.1 specs into Naftiko capabilities, with support for Digest auth, API key, OAuth2 client credentials, and path/query parameter mapping
• Swagger 2.0 — automatic up-conversion to OAS 3.x on import, with parse warnings surfaced to the user
• OAS Export — generate OpenAPI 3.0 specs from capabilities, including OAuth2 tokenUrl, scopes, and Apigee-specific variants
• JSON output format — CLI can now output imported capabilities as JSON
• Refactored CLI commands to Callable pattern with original property name preservation (#295)

🧩 Inline Scripting Steps

Capability orchestration now supports inline code steps alongside declarative call steps. Write transformation logic directly in Groovy, JavaScript, or Python without leaving YAML:

• Groovy, JavaScript, and Python inline script steps with sandboxed execution
• Control Port governance: runtime enable/disable, allowed-languages whitelist, statement limits
• Hardened sandbox — constructor/class-expression blocking in Groovy, script timeouts, safe path resolution
• Full documentation across wiki, skill, and README (#300)

🔭 Observability & Control Port

A complete observability stack, built on OpenTelemetry and exposed through a new Control Port adapter:

• Distributed tracing — W3C Trace Context propagation from HTTP headers into MCP tool spans, centralised server span creation with stable OTel semantic conventions
• RED metrics — Rate/Error/Duration metrics with Prometheus scrape endpoint
• Dashboarding artifacts — ready-to-use Grafana dashboard and alerting configurations
• Spec-driven configuration — observability settings declared in the capability YAML under the control adapter with polymorphic logs field
• Control Port — health checks, /metrics, /traces, /status endpoints, plus runtime scripting governance via CLI and REST API
• Hardened instrumentation: null-safe OTel SDK boundaries, buffer capacity guards, handled-error metrics (#334)

🔐 OAuth 2.1 Server Authentication

Naftiko can now act as an OAuth 2.1 resource server, securing exposed REST and MCP endpoints:

• Shared adapter chain — reusable OAuth 2.1 authentication built on Restlet
• JWT validation — issuer, audience, not-before (nbf) claim enforcement per RFC 7519
• OIDC discovery — automatic authorizationServerUri metadata resolution
• Refactored OAuth2 restlets: deduplicated constructors, renamed metadataUrl → metadataUri

🧱 Aggregates — DDD-Inspired Domain Functions

A new aggregates section lets you define reusable domain functions once and project them through multiple adapters:

• Define once, expose everywhere — an aggregate function holds inputs, outputs, steps, and semantics; MCP tools and REST operations use ref to inherit
• Runtime delegation — the engine delegates tool/operation calls to the referenced aggregate function at runtime
• Mock output parameters — aggregate functions support mock outputs for testing and prototyping

⚙️ Restlet-Based MCP Transport

The MCP HTTP transport layer has been migrated from Jetty to Restlet, aligning the entire HTTP stack on a single foundation:

• Unified server architecture for both REST and MCP adapters
• HTTPS support enabled for the CLI
• MCP tool hints mapped to ToolAnnotations
• Hardened handler: null/malformed request handling, safe prompt entries, skip malformed tool declarations

🤖 Agent & Contributor Experience

• PR review skill — new on-demand skill for posting inline review comments via GitHub API, with pagination, existing-review detection, and diff-aware hunk targeting
• AGENTS.md — expanded with test ordering rules, template usage enforcement, self-improvement workflow, PowerShell --body-file rule, English-only rule for GitHub interactions
• Naftiko capability skill — enriched with mocking patterns
• copilot-instructions.md redirect to AGENTS.md

📐 Specification & Schema Enrichment

The Naftiko JSON Schema has been significantly enriched:

• Detailed description fields added across ConsumesHttp, RequestBody, Authentication, and MCP Expose sections
• Authentication in MCP Expose — spec section §3.5.4 now documents MCP server authentication
• MockParameter added to schema
• Spectral rules and schema synced to Fabric and Backstage

🔧 Engine Fixes

Several bugs from alpha1 and newly discovered issues have been resolved:

• NPE on API key auth — throw IllegalArgumentException when placement is missing (#212) ✅
• Malformed baseUri URLs — enforce strict baseUri without trailing slash (#184) ✅
• Namespace-qualified references — fix resolution in with parameters and both orchestrated/simple-call paths (#231)
• Mustache templates in with params — resolve before upstream call (#229)
• Step output mappings — resolve in orchestrated mode
• Nested array output — populate items instead of properties for nested array output parameters
• Non-JSON response conversion — convert before applying MCP output mappings
• HTML header row filtering — unified filtering and added markdown section filter
• Nested properties in deserializer — route value to setValue
• Default OTLP endpoint — disable localhost:4317 when no control exposes configuration
• outputRawFormat — read from consumed operation in REST adapter

📦 CI/CD & Quality

• SonarQube hardening — narrow catches, typed throws, SLF4J logger, empty ObjectNode for lookup, exception handling improvements
• Meta-Linter integration — integrated into the build pipeline
• Linux ARM64 CLI builds — native binary now available for linux/arm64
• Maven dual publishing — artifacts published to both GitHub Packages and Sonatype Maven Central
• Javadocs publishing — hosted on Javadoc.io based on Maven Central artifacts
• Version sync automation — Naftiko version synced across pom.xml, YAML fixtures, VS Code package.json, and schema
• Tutorial updates — Step 5, 10 fixtures corrected (XML array mapping, crew-resolver aggregate, REST resource)
• PR check script — fixed PowerShell approved verb usage

⚠️ Known Issues & Limitations

• Sonar Bugs — reduction in progress, not yet at Quality Gate zero (#216)
• Race condition — shared OperationStepExecutor across AggregateFunction instances (#320)
• CLI pre-built binaries — available for macOS ARM64, Linux AMD64, Linux ARM64 (new), and Windows AMD64
• Windows CLI installation — not straightforward (#281)
• Named objects for parameters — planned but not yet implemented (#298)

🔢 By the Numbers

• ~202 commits merged since v1.0.0-alpha1
• 477 files changed, +54,952 / −11,011 lines
• 4 contributors

🙏 Contributors

Huge thanks to the team for shipping this release:

• @jlouvel — Observability stack, control port, OAuth 2.1, Restlet migration, aggregates, scripting, engine fixes
• @eskenazit — Agent skills (PR review, capability), AGENTS.md governance, schema enrichment, specification
• @farah-t-trigui — CI/CD improvements, tutorial rework, Maven dual publishing, Docker packaging
• @jeremnaf — CLI enhancements, version sync automation, meta-linter, native builds

---

Full Changelog: v1.0.0-alpha1...v1.0.0-alpha2