forgeos 0.1.0-alpha.2 → 0.1.0-alpha.21

package/adapters/go/types.go

@@ -0,0 +1,136 @@
+package forge
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+)
+
+const ProtocolVersion = "1.0"
+
+type EntryKind string
+type Risk string
+type Transaction string
+
+const (
+	KindCommand EntryKind = "command"
+	KindQuery   EntryKind = "query"
+
+	RiskRead        Risk = "read"
+	RiskWrite       Risk = "write"
+	RiskDestructive Risk = "destructive"
+	RiskExternal    Risk = "external"
+
+	TransactionReadOnly        Transaction = "read-only"
+	TransactionExternalManaged Transaction = "external-managed"
+	TransactionForgeManaged    Transaction = "forge-managed"
+	TransactionSaga            Transaction = "saga"
+)
+
+type Schema map[string]any
+
+type Manifest struct {
+	ForgeProtocol string         `json:"forgeProtocol"`
+	Language      string         `json:"language"`
+	Framework     string         `json:"framework,omitempty"`
+	Service       Service        `json:"service"`
+	Entries       []Entry        `json:"entries"`
+	Schemas       map[string]any `json:"schemas,omitempty"`
+}
+
+type Service struct {
+	Name      string `json:"name"`
+	Transport string `json:"transport"`
+	BaseURL   string `json:"baseUrl,omitempty"`
+	Command   string `json:"command,omitempty"`
+	Health    string `json:"health,omitempty"`
+}
+
+type Entry struct {
+	Name          string      `json:"name"`
+	Kind          EntryKind   `json:"kind"`
+	Description   string      `json:"description,omitempty"`
+	Path          string      `json:"path,omitempty"`
+	Method        string      `json:"method,omitempty"`
+	InputSchema   any         `json:"inputSchema,omitempty"`
+	OutputSchema  any         `json:"outputSchema,omitempty"`
+	Policy        string      `json:"policy,omitempty"`
+	TenantScoped  bool        `json:"tenantScoped,omitempty"`
+	Transaction   Transaction `json:"transaction,omitempty"`
+	Risk          Risk        `json:"risk,omitempty"`
+	NeedsApproval *bool       `json:"needsApproval,omitempty"`
+	Effects       []string    `json:"effects,omitempty"`
+}
+
+type Auth struct {
+	Kind        string         `json:"kind"`
+	UserID      string         `json:"userId,omitempty"`
+	TenantID    string         `json:"tenantId,omitempty"`
+	Role        string         `json:"role,omitempty"`
+	Roles       []string       `json:"roles,omitempty"`
+	Permissions []string       `json:"permissions,omitempty"`
+	Email       string         `json:"email,omitempty"`
+	Name        string         `json:"name,omitempty"`
+	Claims      map[string]any `json:"claims,omitempty"`
+}
+
+type ForgeCall struct {
+	Service string `json:"service"`
+	Entry   string `json:"entry"`
+	Kind    string `json:"kind"`
+	TraceID string `json:"traceId"`
+}
+
+type Context struct {
+	Auth    Auth
+	Forge   ForgeCall
+	Headers http.Header
+}
+
+type HandlerFunc func(context.Context, *Context, json.RawMessage) (any, error)
+
+type RequestEnvelope struct {
+	Args  json.RawMessage `json:"args"`
+	Auth  Auth            `json:"auth"`
+	Forge ForgeCall       `json:"forge"`
+}
+
+type ResponseEnvelope struct {
+	OK          bool         `json:"ok"`
+	Result      any          `json:"result,omitempty"`
+	Diagnostics []Diagnostic `json:"diagnostics,omitempty"`
+	Error       *ErrorInfo   `json:"error,omitempty"`
+	TraceID     string       `json:"traceId,omitempty"`
+}
+
+type Diagnostic struct {
+	Severity string   `json:"severity"`
+	Code     string   `json:"code"`
+	Message  string   `json:"message"`
+	File     string   `json:"file,omitempty"`
+	FixHint  string   `json:"fixHint,omitempty"`
+	Docs     []string `json:"docs,omitempty"`
+}
+
+type ErrorInfo struct {
+	Code    string `json:"code"`
+	Message string `json:"message"`
+}
+
+func Decode(raw json.RawMessage, target any) error {
+	if len(raw) == 0 || string(raw) == "null" {
+		raw = json.RawMessage("{}")
+	}
+	return json.Unmarshal(raw, target)
+}
+
+func Handle[In any, Out any](handler func(context.Context, *Context, In) (Out, error)) HandlerFunc {
+	return func(ctx context.Context, call *Context, raw json.RawMessage) (any, error) {
+		var input In
+		if err := Decode(raw, &input); err != nil {
+			var zero Out
+			return zero, err
+		}
+		return handler(ctx, call, input)
+	}
+}

package/adapters/java/README.md

@@ -0,0 +1,68 @@
+# Forge Java Adapter
+
+`adapters/java` is the minimal Java SDK for external Forge runtimes. It mirrors
+the Go adapter: register commands and queries, emit a `forge.manifest.json`, and
+serve Forge-compatible HTTP envelopes.
+
+```java
+ForgeRegistry app = Forge.service("billing",
+    Forge.framework("java/jdk-http"),
+    Forge.baseUrl("http://127.0.0.1:8788"));
+
+app.command("createInvoice",
+    Forge.handle(CreateInvoiceInput.class, Billing::createInvoice),
+    Forge.policy("billing.manage"),
+    Forge.tenantScoped(true),
+    Forge.needsApproval(true),
+    Forge.inputSchema(Schemas.object(Map.of("title", Schemas.string()), "title")));
+
+app.query("listInvoices",
+    Forge.handle(EmptyInput.class, Billing::listInvoices),
+    Forge.policy("billing.manage"),
+    Forge.tenantScoped(true),
+    Forge.readOnly());
+
+ForgeHttpHandler.listen(app, "127.0.0.1", 8788);
+```
+
+The HTTP handler exposes:
+
+```text
+GET  /health
+GET  /manifest?baseUrl=http://127.0.0.1:8788
+POST /commands/:name
+POST /queries/:name
+```
+
+The handler accepts Forge runtime envelopes and returns Forge response
+envelopes:
+
+```json
+{
+  "args": { "title": "Invoice" },
+  "auth": { "kind": "user", "userId": "u1", "tenantId": "t1", "role": "admin" },
+  "forge": { "service": "billing", "entry": "createInvoice", "kind": "command", "traceId": "trace_..." }
+}
+```
+
+Build locally:
+
+```bash
+mvn -f adapters/java/pom.xml install
+mvn -f examples/java-billing/pom.xml package
+```
+
+Emit and import a manifest:
+
+```bash
+java -jar examples/java-billing/target/java-billing-0.1.0-alpha.11-all.jar --manifest --base-url http://127.0.0.1:8788 > java-billing.manifest.json
+forge manifest import java-billing.manifest.json --json
+forge generate
+```
+
+Invoke through Forge:
+
+```bash
+forge run billing.createInvoice --args '{"title":"Invoice"}' --role admin --tenant-id tenant-a
+forge query billing.listInvoices --args '{}' --role admin --tenant-id tenant-a
+```

package/adapters/java/pom.xml

@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <groupId>dev.forgeos</groupId>
+  <artifactId>forge-java-adapter</artifactId>
+  <version>0.1.0-alpha.11</version>
+  <name>Forge Java Adapter</name>
+  <description>Minimal Java SDK for Forge external runtimes.</description>
+  <url>https://forgeos.dev</url>
+
+  <licenses>
+    <license>
+      <name>Apache License, Version 2.0</name>
+      <url>https://www.apache.org/licenses/LICENSE-2.0.txt</url>
+    </license>
+  </licenses>
+
+  <properties>
+    <maven.compiler.release>17</maven.compiler.release>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    <jackson.version>2.17.2</jackson.version>
+  </properties>
+
+  <dependencies>
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-databind</artifactId>
+      <version>${jackson.version}</version>
+    </dependency>
+  </dependencies>
+</project>

package/adapters/java/src/main/java/dev/forgeos/adapter/Auth.java

@@ -0,0 +1,20 @@
+package dev.forgeos.adapter;
+
+import java.util.List;
+import java.util.Map;
+
+public record Auth(
+    String kind,
+    String userId,
+    String tenantId,
+    String role,
+    List<String> roles,
+    List<String> permissions,
+    String email,
+    String name,
+    Map<String, Object> claims
+) {
+  public static Auth anonymous() {
+    return new Auth("anonymous", null, null, null, null, null, null, null, null);
+  }
+}

package/adapters/java/src/main/java/dev/forgeos/adapter/Diagnostic.java

@@ -0,0 +1,16 @@
+package dev.forgeos.adapter;
+
+import java.util.List;
+
+public record Diagnostic(
+    String severity,
+    String code,
+    String message,
+    String file,
+    String fixHint,
+    List<String> docs
+) {
+  public static Diagnostic error(String code, String message) {
+    return new Diagnostic("error", code, message, null, null, List.of("docs/forge-protocol.md"));
+  }
+}

package/adapters/java/src/main/java/dev/forgeos/adapter/Entry.java

@@ -0,0 +1,38 @@
+package dev.forgeos.adapter;
+
+import java.util.ArrayList;
+import java.util.List;
+
+public final class Entry {
+  public String name;
+  public String kind;
+  public String description;
+  public String path;
+  public String method;
+  public Object inputSchema;
+  public Object outputSchema;
+  public String policy;
+  public Boolean tenantScoped;
+  public String transaction;
+  public String risk;
+  public Boolean needsApproval;
+  public List<String> effects;
+
+  public Entry copy() {
+    Entry copy = new Entry();
+    copy.name = name;
+    copy.kind = kind;
+    copy.description = description;
+    copy.path = path;
+    copy.method = method;
+    copy.inputSchema = inputSchema;
+    copy.outputSchema = outputSchema;
+    copy.policy = policy;
+    copy.tenantScoped = tenantScoped;
+    copy.transaction = transaction;
+    copy.risk = risk;
+    copy.needsApproval = needsApproval;
+    copy.effects = effects == null ? null : new ArrayList<>(effects);
+    return copy;
+  }
+}

package/adapters/java/src/main/java/dev/forgeos/adapter/EntryKind.java

@@ -0,0 +1,16 @@
+package dev.forgeos.adapter;
+
+public enum EntryKind {
+  COMMAND("command"),
+  QUERY("query");
+
+  private final String value;
+
+  EntryKind(String value) {
+    this.value = value;
+  }
+
+  public String value() {
+    return value;
+  }
+}

package/adapters/java/src/main/java/dev/forgeos/adapter/ErrorInfo.java

@@ -0,0 +1,4 @@
+package dev.forgeos.adapter;
+
+public record ErrorInfo(String code, String message) {
+}

package/adapters/java/src/main/java/dev/forgeos/adapter/Forge.java

@@ -0,0 +1,94 @@
+package dev.forgeos.adapter;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import java.util.Arrays;
+import java.util.List;
+
+public final class Forge {
+  private Forge() {
+  }
+
+  public static ForgeRegistry service(String serviceName, ForgeRegistry.RegistryOption... options) {
+    return new ForgeRegistry(serviceName, options);
+  }
+
+  public static ForgeRegistry.RegistryOption framework(String value) {
+    return registry -> registry.setFramework(value);
+  }
+
+  public static ForgeRegistry.RegistryOption baseUrl(String value) {
+    return registry -> registry.setBaseUrl(value);
+  }
+
+  public static ForgeRegistry.RegistryOption health(String path) {
+    return registry -> registry.setHealth(path);
+  }
+
+  public static ForgeRegistry.RegistryOption schemaRef(String name, Object schema) {
+    return registry -> registry.addSchema(name, schema);
+  }
+
+  public static ForgeRegistry.EntryOption description(String value) {
+    return entry -> entry.description = value;
+  }
+
+  public static ForgeRegistry.EntryOption path(String value) {
+    return entry -> entry.path = value;
+  }
+
+  public static ForgeRegistry.EntryOption method(String value) {
+    return entry -> entry.method = value;
+  }
+
+  public static ForgeRegistry.EntryOption inputSchema(Object schema) {
+    return entry -> entry.inputSchema = schema;
+  }
+
+  public static ForgeRegistry.EntryOption outputSchema(Object schema) {
+    return entry -> entry.outputSchema = schema;
+  }
+
+  public static ForgeRegistry.EntryOption policy(String value) {
+    return entry -> entry.policy = value;
+  }
+
+  public static ForgeRegistry.EntryOption tenantScoped(boolean value) {
+    return entry -> entry.tenantScoped = value;
+  }
+
+  public static ForgeRegistry.EntryOption transaction(TransactionMode value) {
+    return entry -> entry.transaction = value.value();
+  }
+
+  public static ForgeRegistry.EntryOption risk(Risk value) {
+    return entry -> entry.risk = value.value();
+  }
+
+  public static ForgeRegistry.EntryOption needsApproval(boolean value) {
+    return entry -> entry.needsApproval = value;
+  }
+
+  public static ForgeRegistry.EntryOption effects(String... values) {
+    return entry -> entry.effects = List.copyOf(Arrays.asList(values));
+  }
+
+  public static ForgeRegistry.EntryOption readOnly() {
+    return entry -> {
+      entry.transaction = TransactionMode.READ_ONLY.value();
+      entry.risk = Risk.READ.value();
+    };
+  }
+
+  public static <In, Out> ForgeHandler handle(
+      Class<In> inputClass,
+      TypedForgeHandler<In, Out> handler
+  ) {
+    return (context, rawArgs) -> {
+      JsonNode args = rawArgs == null || rawArgs.isNull()
+          ? Json.MAPPER.createObjectNode()
+          : rawArgs;
+      In input = Json.MAPPER.treeToValue(args, inputClass);
+      return handler.handle(context, input);
+    };
+  }
+}

package/adapters/java/src/main/java/dev/forgeos/adapter/ForgeCall.java

@@ -0,0 +1,12 @@
+package dev.forgeos.adapter;
+
+public record ForgeCall(String service, String entry, String kind, String traceId) {
+  public ForgeCall withDefaults(String serviceName, String entryName, String entryKind, String fallbackTraceId) {
+    return new ForgeCall(
+        service == null || service.isBlank() ? serviceName : service,
+        entry == null || entry.isBlank() ? entryName : entry,
+        kind == null || kind.isBlank() ? entryKind : kind,
+        traceId == null || traceId.isBlank() ? fallbackTraceId : traceId
+    );
+  }
+}

package/adapters/java/src/main/java/dev/forgeos/adapter/ForgeContext.java

@@ -0,0 +1,11 @@
+package dev.forgeos.adapter;
+
+import java.util.List;
+import java.util.Map;
+
+public record ForgeContext(
+    Auth auth,
+    ForgeCall forge,
+    Map<String, List<String>> headers
+) {
+}

package/adapters/java/src/main/java/dev/forgeos/adapter/ForgeHandler.java

@@ -0,0 +1,8 @@
+package dev.forgeos.adapter;
+
+import com.fasterxml.jackson.databind.JsonNode;
+
+@FunctionalInterface
+public interface ForgeHandler {
+  Object handle(ForgeContext context, JsonNode args) throws Exception;
+}

package/adapters/java/src/main/java/dev/forgeos/adapter/ForgeHttpHandler.java

@@ -0,0 +1,179 @@
+package dev.forgeos.adapter;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.sun.net.httpserver.Headers;
+import com.sun.net.httpserver.HttpExchange;
+import com.sun.net.httpserver.HttpHandler;
+import com.sun.net.httpserver.HttpServer;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.net.InetSocketAddress;
+import java.net.URI;
+import java.net.URLDecoder;
+import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+public final class ForgeHttpHandler implements HttpHandler {
+  private final ForgeRegistry registry;
+
+  public ForgeHttpHandler(ForgeRegistry registry) {
+    this.registry = registry;
+  }
+
+  public static HttpServer listen(ForgeRegistry registry, String host, int port) throws IOException {
+    HttpServer server = HttpServer.create(new InetSocketAddress(host, port), 0);
+    ForgeHttpHandler handler = new ForgeHttpHandler(registry);
+    server.createContext("/", handler);
+    server.start();
+    return server;
+  }
+
+  @Override
+  public void handle(HttpExchange exchange) throws IOException {
+    String path = exchange.getRequestURI().getPath();
+    try {
+      if (registry.healthPath().equals(path)) {
+        writeJson(exchange, 200, Map.of("ok", true, "service", registry.serviceName()));
+        return;
+      }
+      if ("/manifest".equals(path)) {
+        String baseUrl = queryParams(exchange.getRequestURI()).getOrDefault("baseUrl", registry.baseUrl());
+        writeJson(exchange, 200, registry.manifest(baseUrl));
+        return;
+      }
+      if (path.startsWith("/commands/")) {
+        handleRuntime(exchange, EntryKind.COMMAND, path.substring("/commands/".length()));
+        return;
+      }
+      if (path.startsWith("/queries/")) {
+        handleRuntime(exchange, EntryKind.QUERY, path.substring("/queries/".length()));
+        return;
+      }
+      writeError(exchange, 404, traceIdFrom(exchange, null), "FORGE_JAVA_ROUTE_NOT_FOUND", "route not found");
+    } catch (Exception error) {
+      writeError(exchange, 500, traceIdFrom(exchange, null), "FORGE_JAVA_HANDLER_FAILED", error.getMessage());
+    }
+  }
+
+  private void handleRuntime(HttpExchange exchange, EntryKind kind, String rawName) throws IOException {
+    String name = decode(rawName);
+    if (!"POST".equals(exchange.getRequestMethod()) && !"GET".equals(exchange.getRequestMethod())) {
+      writeError(exchange, 405, traceIdFrom(exchange, null), "FORGE_JAVA_METHOD_NOT_ALLOWED", "external entry only accepts GET or POST");
+      return;
+    }
+
+    ForgeRegistry.RegisteredEntry registered = registry.lookup(kind, name);
+    if (registered == null) {
+      writeError(exchange, 404, traceIdFrom(exchange, null), "FORGE_JAVA_ENTRY_NOT_FOUND", "external entry not found");
+      return;
+    }
+
+    RequestEnvelope envelope;
+    try {
+      envelope = readEnvelope(exchange);
+    } catch (Exception error) {
+      writeError(exchange, 400, traceIdFrom(exchange, null), "FORGE_JAVA_BAD_REQUEST", error.getMessage());
+      return;
+    }
+
+    String traceId = traceIdFrom(exchange, envelope);
+    ForgeCall forge = envelope.forge() == null
+        ? new ForgeCall(registry.serviceName(), name, kind.value(), traceId)
+        : envelope.forge().withDefaults(registry.serviceName(), name, kind.value(), traceId);
+    Auth auth = envelope.auth() == null || envelope.auth().kind() == null
+        ? authFromHeaders(exchange.getRequestHeaders())
+        : envelope.auth();
+
+    ForgeContext context = new ForgeContext(auth, forge, exchange.getRequestHeaders());
+    try {
+      Object result = registered.handler().handle(context, envelope.args());
+      writeJson(exchange, 200, ResponseEnvelope.ok(result, forge.traceId()));
+    } catch (Exception error) {
+      writeError(exchange, 500, forge.traceId(), "FORGE_JAVA_HANDLER_FAILED", error.getMessage());
+    }
+  }
+
+  private RequestEnvelope readEnvelope(HttpExchange exchange) throws IOException {
+    if ("GET".equals(exchange.getRequestMethod())) {
+      String args = queryParams(exchange.getRequestURI()).getOrDefault("args", "{}");
+      JsonNode argsNode = Json.MAPPER.readTree(args);
+      return new RequestEnvelope(argsNode, null, null);
+    }
+
+    try (InputStream body = exchange.getRequestBody()) {
+      byte[] bytes = body.readAllBytes();
+      if (bytes.length == 0) {
+        return new RequestEnvelope(Json.MAPPER.createObjectNode(), null, null);
+      }
+      RequestEnvelope envelope = Json.MAPPER.readValue(bytes, RequestEnvelope.class);
+      JsonNode args = envelope.args() == null ? Json.MAPPER.createObjectNode() : envelope.args();
+      return new RequestEnvelope(args, envelope.auth(), envelope.forge());
+    }
+  }
+
+  private static Auth authFromHeaders(Headers headers) {
+    String kind = firstHeader(headers, "x-forge-auth-kind");
+    if (kind == null || kind.isBlank()) {
+      kind = "anonymous";
+    }
+    return new Auth(
+        kind,
+        firstHeader(headers, "x-forge-user-id"),
+        firstHeader(headers, "x-forge-tenant-id"),
+        firstHeader(headers, "x-forge-role"),
+        null,
+        null,
+        null,
+        null,
+        null
+    );
+  }
+
+  private static String traceIdFrom(HttpExchange exchange, RequestEnvelope envelope) {
+    if (envelope != null && envelope.forge() != null && envelope.forge().traceId() != null) {
+      return envelope.forge().traceId();
+    }
+    return firstHeader(exchange.getRequestHeaders(), "x-forge-trace-id");
+  }
+
+  private static String firstHeader(Headers headers, String name) {
+    List<String> values = headers.get(name);
+    if (values == null || values.isEmpty()) {
+      values = headers.get(name.toLowerCase());
+    }
+    return values == null || values.isEmpty() ? null : values.get(0);
+  }
+
+  private static Map<String, String> queryParams(URI uri) {
+    Map<String, String> params = new HashMap<>();
+    String query = uri.getRawQuery();
+    if (query == null || query.isBlank()) {
+      return params;
+    }
+    for (String part : query.split("&")) {
+      String[] pieces = part.split("=", 2);
+      params.put(decode(pieces[0]), pieces.length > 1 ? decode(pieces[1]) : "");
+    }
+    return params;
+  }
+
+  private static String decode(String value) {
+    return URLDecoder.decode(value, StandardCharsets.UTF_8);
+  }
+
+  private static void writeError(HttpExchange exchange, int status, String traceId, String code, String message) throws IOException {
+    writeJson(exchange, status, ResponseEnvelope.error(code, message, traceId));
+  }
+
+  private static void writeJson(HttpExchange exchange, int status, Object body) throws IOException {
+    byte[] bytes = Json.MAPPER.writeValueAsBytes(body);
+    exchange.getResponseHeaders().set("content-type", "application/json");
+    exchange.sendResponseHeaders(status, bytes.length);
+    try (OutputStream response = exchange.getResponseBody()) {
+      response.write(bytes);
+    }
+  }
+}