diff --git a/Makefile b/Makefile index d449ad033..dc8ab5025 100644 --- a/Makefile +++ b/Makefile @@ -8,7 +8,7 @@ ci-build: install proto http-api-docs install: grpc-install api-linter-install buf-install # Run all linters and compile proto files. -proto: grpc http-api-docs nexus-rpc-yaml +proto: grpc http-api-docs nexus-rpc-yaml system-nexus-wit ######################################################################## ##### Variables ###### @@ -17,7 +17,9 @@ GOPATH := $(shell go env GOPATH) endif GOBIN := $(if $(shell go env GOBIN),$(shell go env GOBIN),$(GOPATH)/bin) -PATH := $(GOBIN):$(PATH) +CARGO_HOME ?= $(HOME)/.cargo +CARGO_BIN := $(CARGO_HOME)/bin +PATH := $(GOBIN):$(CARGO_BIN):$(PATH) STAMPDIR := .stamp COLOR := "\e[1;36m%s\e[0m\n" @@ -33,6 +35,8 @@ PROTO_PATHS = paths=source_relative:$(PROTO_OUT) OAPI_OUT := openapi OAPI3_PATH := .components.schemas.Payload +NEX_GEN ?= nex-gen + $(PROTO_OUT): mkdir $(PROTO_OUT) @@ -137,6 +141,24 @@ nexus-rpc-yaml-install: printf $(COLOR) "Build and install protoc-gen-nexus-rpc-yaml..." @cd cmd/protoc-gen-nexus-rpc-yaml && go install . +##### Compile system Nexus WIT files ##### +system-nexus-wit: system-nexus-wit-install nex-gen-install + printf $(COLOR) "Generate system Nexus WIT..." + protoc -I $(PROTO_ROOT) \ + --system-nexus-wit_opt=output=nexus/workflow-service.wit \ + --system-nexus-wit_opt=nex_gen=$(NEX_GEN) \ + --system-nexus-wit_opt=linked_input=nexus/deps \ + --system-nexus-wit_out=. \ + temporal/api/workflowservice/v1/service.proto + +system-nexus-wit-install: + printf $(COLOR) "Build and install protoc-gen-system-nexus-wit..." + @cd cmd/protoc-gen-system-nexus-wit && go install . + +nex-gen-install: + printf $(COLOR) "Install nex-gen if missing..." + command -v $(NEX_GEN) >/dev/null || cargo install nex-gen + ##### Clean ##### clean: printf $(COLOR) "Delete generated go files..." diff --git a/README.md b/README.md index 788613ae8..34a75bd19 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ Install as git submodule to the project. ## Contribution Make your change to the temporal/proto files, and run `make` to update the openapi definitions. +Rust is also required because `make` installs and runs `nex-gen` when regenerating system Nexus WIT files. ## Breaking changes diff --git a/cmd/protoc-gen-system-nexus-wit/generator.go b/cmd/protoc-gen-system-nexus-wit/generator.go new file mode 100644 index 000000000..b30202078 --- /dev/null +++ b/cmd/protoc-gen-system-nexus-wit/generator.go @@ -0,0 +1,187 @@ +package main + +import ( + "fmt" + "os" + "os/exec" + "path/filepath" + "slices" + "strings" + + nexusannotationsv1 "github.com/nexus-rpc/nexus-proto-annotations/go/nexusannotations/v1" + "google.golang.org/protobuf/compiler/protogen" + "google.golang.org/protobuf/proto" + "google.golang.org/protobuf/types/descriptorpb" +) + +type params struct { + nexGen string + output string + input string + linkedInputs []string +} + +// parseParams parses the comma-separated key=value parameter string provided by protoc. +// +// - output: required. Path to the WIT file to generate, relative to the +// --system-nexus-wit_out directory. Example: "nexus/temporal-system.wit". +// +// - nex_gen: optional. Path to the nex-gen binary. Defaults to "nex-gen". +// +// - linked_input: optional, repeatable. Additional WIT input passed to +// nex-gen after the main input. +// +// - input: optional. Existing WIT file to update. Defaults to output, so +// existing handwritten annotations and type refinements are preserved when +// regenerating in place. +func parseParams(raw string) (params, error) { + p := params{ + nexGen: "nex-gen", + } + if raw == "" { + return p, nil + } + for kv := range strings.SplitSeq(raw, ",") { + key, value, ok := strings.Cut(kv, "=") + if !ok { + return p, fmt.Errorf("invalid parameter %q: expected key=value", kv) + } + switch key { + case "nex_gen": + p.nexGen = value + case "output": + p.output = value + case "input": + p.input = value + case "linked_input": + p.linkedInputs = append(p.linkedInputs, value) + default: + return p, fmt.Errorf("unknown parameter %q", key) + } + } + return p, nil +} + +func generate(gen *protogen.Plugin) error { + p, err := parseParams(gen.Request.GetParameter()) + if err != nil { + return err + } + if p.output == "" { + return fmt.Errorf("missing required output parameter") + } + if p.input == "" { + p.input = p.output + } + + rpcs := exposedRPCs(gen) + if len(rpcs) == 0 { + return fmt.Errorf("no proto RPCs are marked as exposed Nexus operations") + } + + tempDir, err := os.MkdirTemp("", "system-nexus-wit-*") + if err != nil { + return err + } + defer os.RemoveAll(tempDir) + + descriptorPath := filepath.Join(tempDir, "temporal_api.bin") + if err := writeDescriptorSet(gen, descriptorPath); err != nil { + return err + } + + tempOutput := filepath.Join(tempDir, "system-nexus.wit") + input := "" + if _, err := os.Stat(p.input); err == nil { + if err := copyFile(p.input, tempOutput); err != nil { + return err + } + input = tempOutput + } else if !os.IsNotExist(err) { + return err + } + + for _, rpc := range rpcs { + if err := runAddRPC(p.nexGen, descriptorPath, rpc, tempOutput, input, p.linkedInputs); err != nil { + return err + } + input = tempOutput + } + + content, err := os.ReadFile(tempOutput) + if err != nil { + return err + } + _, err = gen.NewGeneratedFile(p.output, "").Write(content) + return err +} + +func exposedRPCs(gen *protogen.Plugin) []string { + var rpcs []string + for _, f := range gen.Files { + if !f.Generate { + continue + } + for _, svc := range f.Services { + for _, m := range svc.Methods { + if isExposedOperation(m) { + rpcs = append(rpcs, string(m.Desc.FullName())) + } + } + } + } + return rpcs +} + +func isExposedOperation(m *protogen.Method) bool { + opts, ok := m.Desc.Options().(*descriptorpb.MethodOptions) + if !ok || opts == nil { + return false + } + if !proto.HasExtension(opts, nexusannotationsv1.E_Operation) { + return false + } + tags := proto.GetExtension(opts, nexusannotationsv1.E_Operation).(*nexusannotationsv1.OperationOptions).GetTags() + return slices.Contains(tags, "exposed") +} + +func writeDescriptorSet(gen *protogen.Plugin, descriptorPath string) error { + data, err := proto.Marshal(&descriptorpb.FileDescriptorSet{ + File: gen.Request.GetProtoFile(), + }) + if err != nil { + return err + } + return os.WriteFile(descriptorPath, data, 0o644) +} + +func runAddRPC(nexGen string, descriptors string, rpc string, output string, input string, linkedInputs []string) error { + args := []string{ + "add-rpc", + "--descriptors", descriptors, + "--rpc", rpc, + "--output", output, + } + if input != "" { + args = append(args, "--input", input) + } + for _, linkedInput := range linkedInputs { + args = append(args, "--input", linkedInput) + } + + command := exec.Command(nexGen, args...) + command.Stdout = os.Stdout + command.Stderr = os.Stderr + if err := command.Run(); err != nil { + return fmt.Errorf("%s %s: %w", nexGen, strings.Join(args, " "), err) + } + return nil +} + +func copyFile(source string, destination string) error { + content, err := os.ReadFile(source) + if err != nil { + return err + } + return os.WriteFile(destination, content, 0o644) +} diff --git a/cmd/protoc-gen-system-nexus-wit/go.mod b/cmd/protoc-gen-system-nexus-wit/go.mod new file mode 100644 index 000000000..222e32187 --- /dev/null +++ b/cmd/protoc-gen-system-nexus-wit/go.mod @@ -0,0 +1,8 @@ +module github.com/temporalio/api/cmd/protoc-gen-system-nexus-wit + +go 1.25.4 + +require ( + github.com/nexus-rpc/nexus-proto-annotations v0.0.0-20260330194009-e558d6edaf84 + google.golang.org/protobuf v1.36.1 +) diff --git a/cmd/protoc-gen-system-nexus-wit/go.sum b/cmd/protoc-gen-system-nexus-wit/go.sum new file mode 100644 index 000000000..c96f6a1c5 --- /dev/null +++ b/cmd/protoc-gen-system-nexus-wit/go.sum @@ -0,0 +1,8 @@ +github.com/google/go-cmp v0.5.5 h1:Khx7svrCpmxxtHBq5j2mp/xVjsi8hQMfNLvJFAlrGgU= +github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= +github.com/nexus-rpc/nexus-proto-annotations v0.0.0-20260330194009-e558d6edaf84 h1:SWHt3Coj0VvF0Km1A0wlY+IjnHKsjQLgO29io84r3wY= +github.com/nexus-rpc/nexus-proto-annotations v0.0.0-20260330194009-e558d6edaf84/go.mod h1:n3UjF1bPCW8llR8tHvbxJ+27yPWrhpo8w/Yg1IOuY0Y= +golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543 h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4= +golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= +google.golang.org/protobuf v1.36.1 h1:yBPeRvTftaleIgM3PZ/WBIZ7XM/eEYAaEyCwvyjq/gk= +google.golang.org/protobuf v1.36.1/go.mod h1:9fA7Ob0pmnwhb644+1+CVWFRbNajQ6iRojtC/QF5bRE= diff --git a/cmd/protoc-gen-system-nexus-wit/main.go b/cmd/protoc-gen-system-nexus-wit/main.go new file mode 100644 index 000000000..fb29e5fe0 --- /dev/null +++ b/cmd/protoc-gen-system-nexus-wit/main.go @@ -0,0 +1,11 @@ +// protoc-gen-system-nexus-wit generates Nexus WIT from proto service +// methods annotated with option (nexusannotations.v1.operation).tags = "exposed". +package main + +import "google.golang.org/protobuf/compiler/protogen" + +func main() { + protogen.Options{}.Run(func(gen *protogen.Plugin) error { + return generate(gen) + }) +} diff --git a/nexus/deps/nexus-temporal-types/model.wit b/nexus/deps/nexus-temporal-types/model.wit new file mode 100644 index 000000000..1cc9fb8a0 --- /dev/null +++ b/nexus/deps/nexus-temporal-types/model.wit @@ -0,0 +1,149 @@ +package nexus:temporal-types@1.0.0; + +interface model { + /// String-shaped placeholder for semantic types that generators reinterpret. + type placeholder = string; + + /// @nexus.proto "temporal.api.common.v1.Payload" typescript-package="@temporalio/proto" + /// @nexus.type python="typing.Any" typescript="common.Payload" typescript-package="@temporalio/common" + type payload = placeholder; + + /// @nexus.proto "temporal.api.common.v1.Payloads" + /// typescript-package="@temporalio/proto" + type payloads = list; + + /// Callable result annotation for workflow functions. + /// @nexus.type + /// python="collections.abc.Awaitable[WorkflowResult]" + /// typescript="Promise" + type workflow-result = placeholder; + + /// Receiver/context argument for workflow callable method forms. + /// @nexus.type python="typing.Any" typescript="any" + type callable-prefix = placeholder; + + /// @nexus.function-args + /// varargs=true + /// param="args" + /// typescript-drop-prefix=true + workflow-call: async func(callable-prefix: callable-prefix, args: payloads) -> workflow-result; + + /// Callable result annotation for signal functions. + /// @nexus.type python="None | collections.abc.Awaitable[None]" typescript="void" + type signal-result = placeholder; + + /// @nexus.function-args + /// varargs=true + /// param="signal-args" + /// typescript-drop-prefix=true + signal-call: func(callable-prefix: callable-prefix, signal-args: payloads) -> signal-result; + + /// @nexus.proto "temporal.api.common.v1.WorkflowType" typescript-package="@temporalio/proto" + /// @nexus.type python="str" typescript="string" + type workflow-type = placeholder; + + /// @nexus.function + /// primary=true + /// signature="workflow-call" + /// args-field="input" + /// result-type-parameter="WorkflowResult" + /// alternate-type="workflow-type" + /// @nexus.add-rpc-compatible-with "workflow-type" + type workflow-function = placeholder; + + /// @nexus.function + /// signature="signal-call" + /// args-field="signal-input" + /// alternate-type="string" + /// python-converter="signal_function_to_proto" + /// typescript-converter="signalFunctionToProto" + /// @nexus.add-rpc-compatible-with "string" + /// @nexus.typescript-with-arguments + /// signature="signal-call" + /// args-field="signal-input" + /// alternate-type="string" + /// value-type="workflow.SignalDefinition" + /// args-type="Value extends workflow.SignalDefinition ? Args : never" + /// name-expr="value.name" + /// typescript-package="@temporalio/workflow" + type signal-function = placeholder; + + /// @nexus.proto "temporal.api.common.v1.RetryPolicy" typescript-package="@temporalio/proto" + /// @nexus.type + /// python="temporalio.common.RetryPolicy" + /// typescript="common.RetryPolicy" + /// typescript-package="@temporalio/common" + type retry-policy = placeholder; + + /// @nexus.proto "temporal.api.taskqueue.v1.TaskQueue" typescript-package="@temporalio/proto" + /// @nexus.type python="str" typescript="string" + type task-queue = placeholder; + + /// @nexus.proto "temporal.api.common.v1.Memo" typescript-package="@temporalio/proto" + /// @nexus.type python="collections.abc.Mapping[str, typing.Any]" typescript="Record" + type memo = placeholder; + + /// @nexus.proto "temporal.api.common.v1.SearchAttributes" typescript-package="@temporalio/proto" + /// @nexus.type + /// python="temporalio.common.TypedSearchAttributes" + /// typescript="common.TypedSearchAttributes" + /// typescript-package="@temporalio/common" + type search-attributes = placeholder; + + /// @nexus.proto "temporal.api.common.v1.Priority" typescript-package="@temporalio/proto" + /// @nexus.type + /// python="temporalio.common.Priority" + /// typescript="common.Priority" + /// typescript-package="@temporalio/common" + type priority = placeholder; + + /// @nexus.proto "temporal.api.workflow.v1.VersioningOverride" typescript-package="@temporalio/proto" + /// @nexus.type + /// python="temporalio.common.VersioningOverride" + /// typescript="common.VersioningOverride" + /// typescript-package="@temporalio/common" + type versioning-override = placeholder; + + /// @nexus.proto "google.protobuf.Duration" typescript-package="@temporalio/proto" + /// @nexus.type + /// python="datetime.timedelta" + /// typescript="common.Duration" + /// typescript-package="@temporalio/common" + type duration = placeholder; + + /// @nexus.proto "temporal.api.enums.v1.WorkflowIdReusePolicy" typescript-package="@temporalio/proto" + /// @nexus.type + /// python="temporalio.common.WorkflowIDReusePolicy" + /// typescript="common.WorkflowIdReusePolicy" + /// typescript-package="@temporalio/common" + enum workflow-id-reuse-policy { + allow-duplicate, + allow-duplicate-failed-only, + reject-duplicate, + terminate-if-running, + } + + /// @nexus.proto "temporal.api.enums.v1.WorkflowIdConflictPolicy" typescript-package="@temporalio/proto" + /// @nexus.type + /// python="temporalio.common.WorkflowIDConflictPolicy" + /// typescript="common.WorkflowIdConflictPolicy" + /// typescript-package="@temporalio/common" + enum workflow-id-conflict-policy { + fail, + use-existing, + terminate-existing, + } + + /// @nexus.proto "temporal.api.sdk.v1.UserMetadata" typescript-package="@temporalio/proto" + /// @nexus.flatten-in-api + record user-metadata { + /// @nexus.doc "Single-line fixed summary for the workflow execution that may appear in UI and CLI. This can be in single-line Temporal Markdown format." + /// @nexus.proto-field "summary" + /// @nexus.flattened-type python="str" typescript="string" + static-summary: option, + /// @nexus.doc "General fixed details for the workflow execution that may appear in UI and CLI. This can be in Temporal Markdown format and can span multiple lines. This value is fixed on the workflow execution and cannot be updated." + /// @nexus.proto-field "details" + /// @nexus.flattened-type python="str" typescript="string" + static-details: option, + } +} diff --git a/nexus/workflow-service.wit b/nexus/workflow-service.wit new file mode 100644 index 000000000..1b7f10656 --- /dev/null +++ b/nexus/workflow-service.wit @@ -0,0 +1,119 @@ +package temporal:nexus@1.0.0; + +world system { + export workflow-service; +} + +/// @nexus.endpoint "__temporal_system" +/// @nexus.service-name "temporal.api.workflowservice.v1.WorkflowService" +/// @nexus.delay-load-temporalio-workflow +/// @nexus.experimental +interface workflow-service { + use nexus:temporal-types/model@1.0.0.{ + duration, + memo, + payloads, + placeholder, + priority, + retry-policy, + search-attributes, + signal-function, + task-queue, + user-metadata, + versioning-override, + workflow-function, + workflow-id-conflict-policy, + workflow-id-reuse-policy, + }; + + /// @nexus.doc "Request fields for signaling a workflow, starting it first if needed." + /// @nexus.experimental + /// @nexus.proto "temporal.api.workflowservice.v1.SignalWithStartWorkflowExecutionRequest" typescript-package="@temporalio/proto" + record signal-with-start-workflow-request { + /// @nexus.doc + /// python="Workflow type name or callable identifying the workflow to start." + /// typescript="Workflow type name or workflow function identifying the workflow to start." + /// @nexus.proto-field "workflow_type" + workflow: workflow-function, + /// @nexus.doc "Unique identifier for the workflow execution." + /// @nexus.proto-field "workflow_id" + id: string, + /// @nexus.doc "Task queue to run the workflow on." + task-queue: task-queue, + /// @nexus.doc + /// python="Signal name or callable to send with the start request." + /// typescript="Signal name or signal definition to send with the start request." + /// @nexus.proto-field "signal_name" + signal: signal-function, + /// @nexus.doc "Total workflow execution timeout, including retries and continue-as-new." + /// @nexus.proto-field "workflow_execution_timeout" + execution-timeout: option, + /// @nexus.doc "Timeout of a single workflow run." + /// @nexus.proto-field "workflow_run_timeout" + run-timeout: option, + /// @nexus.doc "Timeout of a single workflow task." + /// @nexus.proto-field "workflow_task_timeout" + task-timeout: option, + /// @nexus.omit + identity: placeholder, + /// @nexus.doc "Request ID used to deduplicate workflow start requests." + request-id: option, + /// @nexus.doc "Behavior when a closed workflow with the same ID exists. Default is allow-duplicate." + /// @nexus.proto-field "workflow_id_reuse_policy" + /// @nexus.default "allow-duplicate" + id-reuse-policy: workflow-id-reuse-policy, + /// @nexus.doc "Behavior when a workflow is currently running with the same ID. Set to use-existing for idempotent deduplication on workflow ID. Cannot be set if id-reuse-policy is terminate-if-running." + /// @nexus.proto-field "workflow_id_conflict_policy" + id-conflict-policy: option, + /// @nexus.doc "Retry policy for the workflow." + retry-policy: option, + /// @nexus.doc "Cron schedule for recurring workflow executions. See https://docs.temporal.io/cron-job." + cron-schedule: option, + /// @nexus.doc "Memo for the workflow." + memo: option, + /// @nexus.doc "Typed search attributes for the workflow." + search-attributes: option, + /// @nexus.doc "Priority of the workflow execution." + priority: option, + /// @nexus.doc "Override for workflow versioning behavior." + versioning-override: option, + /// @nexus.doc "Amount of time to wait before starting the workflow. This does not work with cron-schedule." + /// @nexus.proto-field "workflow_start_delay" + start-delay: option, + user-metadata: option, + /// @nexus.source python="workflow_namespace" typescript="workflowNamespace" + namespace: string, + /// @nexus.omit + control: placeholder, + /// @nexus.omit + header: placeholder, + /// @nexus.omit + links: placeholder, + /// @nexus.omit + time-skipping-config: placeholder, + } + + /// @nexus.experimental + /// @nexus.proto "temporal.api.workflowservice.v1.SignalWithStartWorkflowExecutionResponse" typescript-package="@temporalio/proto" + record signal-with-start-workflow-response { + run-id: option, + started: option, + /// @nexus.omit + signal-link: placeholder, + } + + /// @nexus.doc + /// "Signal a workflow, starting it first if needed." + /// returns="A workflow handle to the started workflow." + /// @nexus.output-transform + /// python-type="temporalio.workflow.ExternalWorkflowHandle[WorkflowResult]" + /// python="temporalio.workflow.get_external_workflow_handle(request.id, run_id=result.run_id)" + /// typescript-type="workflow.ExternalWorkflowHandle" + /// typescript="workflow.getExternalWorkflowHandle(request.id, result.runId ?? undefined)" + /// typescript-package="@temporalio/workflow" + /// @nexus.operation name="SignalWithStartWorkflowExecution" + /// @nexus.experimental + signal-with-start-workflow: func( + request: signal-with-start-workflow-request, + ) -> signal-with-start-workflow-response; +}