forgeos 0.1.0-alpha.3 → 0.1.0-alpha.30

package/adapters/go/http.go

@@ -0,0 +1,149 @@
+package forge
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strings"
+)
+
+func (registry *Registry) HTTPHandler() http.Handler {
+	mux := http.NewServeMux()
+	mux.HandleFunc(registry.service.Health, registry.handleHealth)
+	mux.HandleFunc("/manifest", registry.handleManifest)
+	mux.HandleFunc("/commands/", registry.handleRuntime(KindCommand, "/commands/"))
+	mux.HandleFunc("/queries/", registry.handleRuntime(KindQuery, "/queries/"))
+	return mux
+}
+
+func (registry *Registry) handleHealth(response http.ResponseWriter, request *http.Request) {
+	writeJSON(response, http.StatusOK, map[string]any{
+		"ok":      true,
+		"service": registry.service.Name,
+	})
+}
+
+func (registry *Registry) handleManifest(response http.ResponseWriter, request *http.Request) {
+	baseURL := request.URL.Query().Get("baseUrl")
+	if baseURL == "" {
+		baseURL = registry.service.BaseURL
+	}
+	writeJSON(response, http.StatusOK, registry.Manifest(baseURL))
+}
+
+func (registry *Registry) handleRuntime(kind EntryKind, prefix string) http.HandlerFunc {
+	return func(response http.ResponseWriter, request *http.Request) {
+		name := strings.TrimPrefix(request.URL.Path, prefix)
+		registered, ok := registry.lookup[lookupKey(kind, name)]
+		if !ok {
+			writeError(response, http.StatusNotFound, "", "FORGE_GO_ENTRY_NOT_FOUND", "external entry not found")
+			return
+		}
+		if request.Method != http.MethodPost && request.Method != http.MethodGet {
+			writeError(response, http.StatusMethodNotAllowed, "", "FORGE_GO_METHOD_NOT_ALLOWED", "external entry only accepts GET or POST")
+			return
+		}
+
+		envelope, err := readRequestEnvelope(request)
+		traceID := traceIDFrom(request, envelope)
+		if err != nil {
+			writeError(response, http.StatusBadRequest, traceID, "FORGE_GO_BAD_REQUEST", err.Error())
+			return
+		}
+		if envelope.Forge.Service == "" {
+			envelope.Forge.Service = registry.service.Name
+		}
+		if envelope.Forge.Entry == "" {
+			envelope.Forge.Entry = name
+		}
+		if envelope.Forge.Kind == "" {
+			envelope.Forge.Kind = string(kind)
+		}
+		if envelope.Forge.TraceID == "" {
+			envelope.Forge.TraceID = traceID
+		}
+		if envelope.Auth.Kind == "" {
+			envelope.Auth = authFromHeaders(request.Header)
+		}
+
+		call := &Context{
+			Auth:    envelope.Auth,
+			Forge:   envelope.Forge,
+			Headers: request.Header,
+		}
+		result, err := registered.handler(request.Context(), call, envelope.Args)
+		if err != nil {
+			writeError(response, http.StatusInternalServerError, envelope.Forge.TraceID, "FORGE_GO_HANDLER_FAILED", err.Error())
+			return
+		}
+		writeJSON(response, http.StatusOK, ResponseEnvelope{
+			OK:      true,
+			Result:  result,
+			TraceID: envelope.Forge.TraceID,
+		})
+	}
+}
+
+func readRequestEnvelope(request *http.Request) (RequestEnvelope, error) {
+	if request.Method == http.MethodGet {
+		args := request.URL.Query().Get("args")
+		if args == "" {
+			args = "{}"
+		}
+		return RequestEnvelope{Args: json.RawMessage(args)}, nil
+	}
+	defer request.Body.Close()
+	var envelope RequestEnvelope
+	decoder := json.NewDecoder(request.Body)
+	if err := decoder.Decode(&envelope); err != nil {
+		return envelope, err
+	}
+	if len(envelope.Args) == 0 {
+		envelope.Args = json.RawMessage("{}")
+	}
+	if !json.Valid(envelope.Args) {
+		return envelope, errors.New("request args must be valid JSON")
+	}
+	return envelope, nil
+}
+
+func authFromHeaders(headers http.Header) Auth {
+	auth := Auth{Kind: headers.Get("x-forge-auth-kind")}
+	if auth.Kind == "" {
+		auth.Kind = "anonymous"
+	}
+	auth.UserID = headers.Get("x-forge-user-id")
+	auth.TenantID = headers.Get("x-forge-tenant-id")
+	auth.Role = headers.Get("x-forge-role")
+	return auth
+}
+
+func traceIDFrom(request *http.Request, envelope RequestEnvelope) string {
+	if envelope.Forge.TraceID != "" {
+		return envelope.Forge.TraceID
+	}
+	return request.Header.Get("x-forge-trace-id")
+}
+
+func writeError(response http.ResponseWriter, status int, traceID string, code string, message string) {
+	writeJSON(response, status, ResponseEnvelope{
+		OK: false,
+		Diagnostics: []Diagnostic{{
+			Severity: "error",
+			Code:     code,
+			Message:  message,
+			Docs:     []string{"docs/forge-protocol.md"},
+		}},
+		Error: &ErrorInfo{
+			Code:    code,
+			Message: message,
+		},
+		TraceID: traceID,
+	})
+}
+
+func writeJSON(response http.ResponseWriter, status int, body any) {
+	response.Header().Set("content-type", "application/json")
+	response.WriteHeader(status)
+	_ = json.NewEncoder(response).Encode(body)
+}

package/adapters/go/registry.go

@@ -0,0 +1,234 @@
+package forge
+
+import (
+	"encoding/json"
+	"io"
+)
+
+type Registry struct {
+	service   Service
+	framework string
+	schemas   map[string]any
+	entries   []registeredEntry
+	lookup    map[string]registeredEntry
+}
+
+type registeredEntry struct {
+	entry   Entry
+	handler HandlerFunc
+}
+
+type RegistryOption func(*Registry)
+type EntryOption func(*Entry)
+
+func New(serviceName string, options ...RegistryOption) *Registry {
+	registry := &Registry{
+		service: Service{
+			Name:      serviceName,
+			Transport: "http",
+			Health:    "/health",
+		},
+		framework: "net/http",
+		schemas:   map[string]any{},
+		lookup:    map[string]registeredEntry{},
+	}
+	for _, option := range options {
+		option(registry)
+	}
+	return registry
+}
+
+func Framework(value string) RegistryOption {
+	return func(registry *Registry) {
+		registry.framework = value
+	}
+}
+
+func BaseURL(value string) RegistryOption {
+	return func(registry *Registry) {
+		registry.service.BaseURL = value
+	}
+}
+
+func Health(path string) RegistryOption {
+	return func(registry *Registry) {
+		registry.service.Health = path
+	}
+}
+
+func SchemaRef(name string, schema any) RegistryOption {
+	return func(registry *Registry) {
+		registry.schemas[name] = schema
+	}
+}
+
+func (registry *Registry) Command(name string, handler HandlerFunc, options ...EntryOption) {
+	entry := Entry{
+		Name:        name,
+		Kind:        KindCommand,
+		Path:        "/commands/" + name,
+		Method:      "POST",
+		Transaction: TransactionExternalManaged,
+		Risk:        RiskWrite,
+	}
+	registry.add(entry, handler, options...)
+}
+
+func (registry *Registry) Query(name string, handler HandlerFunc, options ...EntryOption) {
+	entry := Entry{
+		Name:        name,
+		Kind:        KindQuery,
+		Path:        "/queries/" + name,
+		Method:      "POST",
+		Transaction: TransactionReadOnly,
+		Risk:        RiskRead,
+	}
+	registry.add(entry, handler, options...)
+}
+
+func (registry *Registry) add(entry Entry, handler HandlerFunc, options ...EntryOption) {
+	for _, option := range options {
+		option(&entry)
+	}
+	registered := registeredEntry{entry: entry, handler: handler}
+	registry.entries = append(registry.entries, registered)
+	registry.lookup[lookupKey(entry.Kind, entry.Name)] = registered
+}
+
+func Description(value string) EntryOption {
+	return func(entry *Entry) {
+		entry.Description = value
+	}
+}
+
+func Path(value string) EntryOption {
+	return func(entry *Entry) {
+		entry.Path = value
+	}
+}
+
+func Method(value string) EntryOption {
+	return func(entry *Entry) {
+		entry.Method = value
+	}
+}
+
+func InputSchema(schema any) EntryOption {
+	return func(entry *Entry) {
+		entry.InputSchema = schema
+	}
+}
+
+func OutputSchema(schema any) EntryOption {
+	return func(entry *Entry) {
+		entry.OutputSchema = schema
+	}
+}
+
+func Policy(value string) EntryOption {
+	return func(entry *Entry) {
+		entry.Policy = value
+	}
+}
+
+func TenantScoped(value bool) EntryOption {
+	return func(entry *Entry) {
+		entry.TenantScoped = value
+	}
+}
+
+func TransactionMode(value Transaction) EntryOption {
+	return func(entry *Entry) {
+		entry.Transaction = value
+	}
+}
+
+func EntryRisk(value Risk) EntryOption {
+	return func(entry *Entry) {
+		entry.Risk = value
+	}
+}
+
+func NeedsApproval(value bool) EntryOption {
+	return func(entry *Entry) {
+		entry.NeedsApproval = &value
+	}
+}
+
+func Effects(values ...string) EntryOption {
+	return func(entry *Entry) {
+		entry.Effects = append([]string{}, values...)
+	}
+}
+
+func ReadOnly() EntryOption {
+	return func(entry *Entry) {
+		entry.Transaction = TransactionReadOnly
+		entry.Risk = RiskRead
+	}
+}
+
+func (registry *Registry) Manifest(baseURL string) Manifest {
+	service := registry.service
+	if baseURL != "" {
+		service.BaseURL = baseURL
+	}
+	entries := make([]Entry, 0, len(registry.entries))
+	for _, registered := range registry.entries {
+		entries = append(entries, registered.entry)
+	}
+	manifest := Manifest{
+		ForgeProtocol: ProtocolVersion,
+		Language:      "go",
+		Framework:     registry.framework,
+		Service:       service,
+		Entries:       entries,
+	}
+	if len(registry.schemas) > 0 {
+		manifest.Schemas = registry.schemas
+	}
+	return manifest
+}
+
+func (registry *Registry) MarshalManifest(baseURL string) ([]byte, error) {
+	return json.MarshalIndent(registry.Manifest(baseURL), "", "  ")
+}
+
+func (registry *Registry) WriteManifest(writer io.Writer, baseURL string) error {
+	encoded, err := registry.MarshalManifest(baseURL)
+	if err != nil {
+		return err
+	}
+	if _, err := writer.Write(encoded); err != nil {
+		return err
+	}
+	_, err = writer.Write([]byte("\n"))
+	return err
+}
+
+func Object(properties map[string]any, required ...string) Schema {
+	schema := Schema{
+		"type":       "object",
+		"properties": properties,
+	}
+	if len(required) > 0 {
+		schema["required"] = required
+	}
+	return schema
+}
+
+func String() Schema {
+	return Schema{"type": "string"}
+}
+
+func Boolean() Schema {
+	return Schema{"type": "boolean"}
+}
+
+func Array(items any) Schema {
+	return Schema{"type": "array", "items": items}
+}
+
+func lookupKey(kind EntryKind, name string) string {
+	return string(kind) + ":" + name
+}

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;
+  }
+}