feat(go-sdk): use generic methods starting Go 1.27

.github/workflows/sdk-go.yml

@@ -21,13 +21,19 @@ defaults:
 jobs:
   compile:
     runs-on: ubuntu-latest
+    # Verify the SDK against both supported Go versions: 1.26 exercises the reflection
+    # (fn any) constructors, 1.27 exercises the generic-method constructors.
+    strategy:
+      fail-fast: false
+      matrix:
+        go-version: ["1.26", "1.27"]
     steps:
       - name: Checkout
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
       - name: Setup Go
         uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6.5.0
         with:
-          go-version: "1.26"
+          go-version: "${{ matrix.go-version }}"
       - name: Compile Go SDK examples
         run: |
           # Find all directories with go.mod files

.pre-commit-config.yaml

@@ -34,7 +34,7 @@ repos:
       - id: check-yaml
         exclude: (^examples/|^cmd/hatchet-cli/cli/templates/)
   - repo: https://github.com/golangci/golangci-lint
-    rev: v2.12.2
+    rev: v2.13.2
     hooks:
       - id: golangci-lint
         args: ["--config=.golangci.yml", "--allow-parallel-runners"]

Taskfile.yaml

@@ -56,7 +56,10 @@ tasks:
         SERVER_INTERNAL_CLIENT_BASE_INHERIT_BASE=false
         EOF
   fmt-go:
-    cmd: gofmt -s -w .
+    # *_go127.go hold Go 1.27 generic methods, which the go1.26 gofmt parser rejects.
+    # gofmt ignores build tags, so those files are excluded here and formatted with a
+    # go1.27+ toolchain instead. -exec ... + batches args to avoid ARG_MAX limits.
+    cmd: find . -type f -name '*.go' -not -name '*_go127.go' -exec gofmt -s -w {} +
   fmt-app:
     dir: frontend/app
     cmd: pnpm run prettier:fix && pnpm run prettier:check
@@ -233,7 +236,10 @@ tasks:
   generate-sdk-docs-go:
     dir: sdks/go
     cmds:
-      - go run ./docs/generator
+      # Pin to Go 1.27+ so the generator's parser can read the generic-method (go1.27)
+      # files and document both the go1.27 and pre-go1.27 signatures. An older toolchain
+      # can't parse the generic files and would emit only the reflection signatures.
+      - GOTOOLCHAIN=go1.27.0 go run ./docs/generator
   generate-sdk-docs-ruby:
     dir: sdks/ruby
     cmds:

frontend/docs/content/docs/reference/go/client.mdx

@@ -197,29 +197,25 @@ Returns:
 
 #### `NewStandaloneDurableTask`
 
-NewStandaloneDurableTask creates a standalone durable task that can be triggered independently. This is a specialized workflow containing only one durable task, making it easier to create simple single-task workflows with durable functionality.
-
-The function parameter must have the signature:
+NewStandaloneDurableTask creates a standalone durable task that can be triggered independently. Like NewStandaloneTask, the input and output types are type parameters checked at compile time and invoked without reflection.
 
 ```go
-func(ctx hatchet.DurableContext, input any) (any, error)
+func(ctx hatchet.DurableContext, input In) (Out, error)
 ```
 
-Function signatures are validated at runtime using reflection.
-
 Options can be any combination of WorkflowOption and TaskOption.
 
 ```go
-func (c *Client) NewStandaloneDurableTask(name string, fn any, options ...StandaloneTaskOption) *StandaloneTask
+func (c *Client) NewStandaloneDurableTask[I, O any](name string, fn func(ctx DurableContext, input I) (O, error), options ...StandaloneTaskOption) *StandaloneTask
 ```
 
 Parameters:
 
-| Name      | Type                      |
-| --------- | ------------------------- |
-| `name`    | `string`                  |
-| `fn`      | `any`                     |
-| `options` | `...StandaloneTaskOption` |
+| Name      | Type                                           |
+| --------- | ---------------------------------------------- |
+| `name`    | `string`                                       |
+| `fn`      | `func(ctx DurableContext, input I) (O, error)` |
+| `options` | `...StandaloneTaskOption`                      |
 
 Returns:
 
@@ -234,24 +230,24 @@ NewStandaloneTask creates a standalone task that can be triggered independently.
 The function parameter must have the signature:
 
 ```go
-func(ctx hatchet.Context, input any) (any, error)
+func(ctx hatchet.Context, input In) (Out, error)
 ```
 
-Function signatures are validated at runtime using reflection.
+The input and output types are type parameters, checked at compile time and invoked without reflection. They are inferred from the function, so existing call sites are unchanged.
 
 Options can be any combination of WorkflowOption and TaskOption.
 
 ```go
-func (c *Client) NewStandaloneTask(name string, fn any, options ...StandaloneTaskOption) *StandaloneTask
+func (c *Client) NewStandaloneTask[I, O any](name string, fn func(ctx Context, input I) (O, error), options ...StandaloneTaskOption) *StandaloneTask
 ```
 
 Parameters:
 
-| Name      | Type                      |
-| --------- | ------------------------- |
-| `name`    | `string`                  |
-| `fn`      | `any`                     |
-| `options` | `...StandaloneTaskOption` |
+| Name      | Type                                    |
+| --------- | --------------------------------------- |
+| `name`    | `string`                                |
+| `fn`      | `func(ctx Context, input I) (O, error)` |
+| `options` | `...StandaloneTaskOption`               |
 
 Returns:
 

frontend/docs/content/docs/reference/go/runnables.mdx

@@ -17,16 +17,16 @@ Workflow defines a Hatchet workflow, which can then declare tasks and be run, sc
 
 Methods:
 
-| Name             | Description                                                                                       |
-| ---------------- | ------------------------------------------------------------------------------------------------- |
-| `GetName`        | GetName returns the resolved workflow name (including namespace if applicable).                   |
-| `NewBatchTask`   | NewBatchTask transforms a function into a Hatchet batch task that runs as part of a workflow.     |
-| `NewDurableTask` | NewDurableTask transforms a function into a durable Hatchet task that runs as part of a workflow. |
-| `NewTask`        | NewTask transforms a function into a Hatchet task that runs as part of a workflow.                |
-| `OnFailure`      | OnFailure sets a failure handler for the workflow.                                                |
-| `Run`            | Run executes the workflow with the provided input and waits for completion.                       |
-| `RunMany`        | RunMany executes multiple workflow instances with different inputs.                               |
-| `RunNoWait`      | RunNoWait executes the workflow with the provided input without waiting for completion.           |
+| Name             | Description                                                                                             |
+| ---------------- | ------------------------------------------------------------------------------------------------------- |
+| `GetName`        | GetName returns the resolved workflow name (including namespace if applicable).                         |
+| `NewBatchTask`   | NewBatchTask transforms a function into a Hatchet batch task that runs as part of a workflow.           |
+| `NewDurableTask` | NewDurableTask transforms a typed function into a durable Hatchet task that runs as part of a workflow. |
+| `NewTask`        | NewTask transforms a typed function into a Hatchet task that runs as part of a workflow.                |
+| `OnFailure`      | OnFailure sets a typed failure handler for the workflow.                                                |
+| `Run`            | Run executes the workflow with the provided input and waits for completion.                             |
+| `RunMany`        | RunMany executes multiple workflow instances with different inputs.                                     |
+| `RunNoWait`      | RunNoWait executes the workflow with the provided input without waiting for completion.                 |
 
 ### Functions
 
@@ -85,27 +85,23 @@ Returns:
 
 #### `NewDurableTask`
 
-NewDurableTask transforms a function into a durable Hatchet task that runs as part of a workflow.
-
-The function parameter must have the signature:
+NewDurableTask transforms a typed function into a durable Hatchet task that runs as part of a workflow. Like NewTask, the input and output types are type parameters checked at compile time. On Go 1.26 and earlier, fn is typed any and validated at runtime instead.
 
 ```go
-func(ctx hatchet.DurableContext, input any) (any, error)
+func(ctx hatchet.DurableContext, input In) (Out, error)
 ```
 
-Function signatures are validated at runtime using reflection.
-
 ```go
-func (w *Workflow) NewDurableTask(name string, fn any, options ...TaskOption) *Task
+func (w *Workflow) NewDurableTask[I, O any](name string, fn func(ctx DurableContext, input I) (O, error), options ...TaskOption) *Task
 ```
 
 Parameters:
 
-| Name      | Type            |
-| --------- | --------------- |
-| `name`    | `string`        |
-| `fn`      | `any`           |
-| `options` | `...TaskOption` |
+| Name      | Type                                           |
+| --------- | ---------------------------------------------- |
+| `name`    | `string`                                       |
+| `fn`      | `func(ctx DurableContext, input I) (O, error)` |
+| `options` | `...TaskOption`                                |
 
 Returns:
 
@@ -115,27 +111,25 @@ Returns:
 
 #### `NewTask`
 
-NewTask transforms a function into a Hatchet task that runs as part of a workflow.
+NewTask transforms a typed function into a Hatchet task that runs as part of a workflow.
 
-The function parameter must have the signature:
+The input and output types are type parameters inferred from the function, so the signature is checked at compile time and invoked directly. On Go 1.26 and earlier, fn is typed any and validated at runtime instead.
 
 ```go
-func(ctx hatchet.Context, input any) (any, error)
+func(ctx hatchet.Context, input In) (Out, error)
 ```
 
-Function signatures are validated at runtime using reflection.
-
 ```go
-func (w *Workflow) NewTask(name string, fn any, options ...TaskOption) *Task
+func (w *Workflow) NewTask[I, O any](name string, fn func(ctx Context, input I) (O, error), options ...TaskOption) *Task
 ```
 
 Parameters:
 
-| Name      | Type            |
-| --------- | --------------- |
-| `name`    | `string`        |
-| `fn`      | `any`           |
-| `options` | `...TaskOption` |
+| Name      | Type                                    |
+| --------- | --------------------------------------- |
+| `name`    | `string`                                |
+| `fn`      | `func(ctx Context, input I) (O, error)` |
+| `options` | `...TaskOption`                         |
 
 Returns:
 
@@ -145,17 +139,21 @@ Returns:
 
 #### `OnFailure`
 
-OnFailure sets a failure handler for the workflow. The handler will be called when any task in the workflow fails.
+OnFailure sets a typed failure handler for the workflow. It runs when any task in the workflow fails and receives the same input the workflow was triggered with. On Go 1.26 and earlier, fn is typed any and validated at runtime instead.
+
+```go
+func(ctx hatchet.Context, input In) (Out, error)
+```
 
 ```go
-func (w *Workflow) OnFailure(fn any)
+func (w *Workflow) OnFailure[I, O any](fn func(ctx Context, input I) (O, error))
 ```
 
 Parameters:
 
-| Name | Type  |
-| ---- | ----- |
-| `fn` | `any` |
+| Name | Type                                    |
+| ---- | --------------------------------------- |
+| `fn` | `func(ctx Context, input I) (O, error)` |
 
 #### `Run`
 
@@ -234,7 +232,7 @@ Methods:
 | Name        | Description                                                                                    |
 | ----------- | ---------------------------------------------------------------------------------------------- |
 | `GetName`   | GetName returns the name of the standalone task.                                               |
-| `OnFailure` | OnFailure sets a failure handler for the standalone task.                                      |
+| `OnFailure` | OnFailure sets a typed failure handler for the standalone task.                                |
 | `Run`       | Run executes the standalone task with the provided input and waits for completion.             |
 | `RunMany`   | RunMany executes multiple standalone task instances with different inputs.                     |
 | `RunNoWait` | RunNoWait executes the standalone task with the provided input without waiting for completion. |
@@ -257,17 +255,17 @@ Returns:
 
 #### `OnFailure`
 
-OnFailure sets a failure handler for the standalone task. The handler will be called when the standalone task fails.
+OnFailure sets a typed failure handler for the standalone task. It runs when the task fails and receives the same input the task was triggered with. The input and output types are type parameters, inferred from the handler and invoked without reflection.
 
 ```go
-func (st *StandaloneTask) OnFailure(fn any)
+func (st *StandaloneTask) OnFailure[I, O any](fn func(ctx Context, input I) (O, error))
 ```
 
 Parameters:
 
-| Name | Type  |
-| ---- | ----- |
-| `fn` | `any` |
+| Name | Type                                    |
+| ---- | --------------------------------------- |
+| `fn` | `func(ctx Context, input I) (O, error)` |
 
 #### `Run`