Add a hook point to the Matching service once a task has been matched or not by 02strich · Pull Request #9311 · temporalio/temporal

02strich · 2026-02-13T00:06:23Z

What changed?

This adds a hook point to the matching service once it has matched a task or decided to spool it.

Why?

This can be leveraged to react to task sync or no-sync match events, while keeping matching service decoupled from the event handling logic.

How did you test it?

CLAassistant · 2026-02-13T00:07:11Z

All committers have signed the CLA.

rkannan82

Looks good to me. Lets add David/Shahab to this.

dnr · 2026-02-18T22:54:07Z

@@ -0,0 +1,36 @@
+package hooks


does this really need to be a new package? if it is a new package, let's remove "TaskHook" as a prefix from all these names to reduce stuttering.

it can't be in matching as that causes a dependency loop. I would love if there was a different existing place instead of creating a new one

dnr · 2026-02-18T22:54:08Z

 		tqConfig,
 		partition.TaskQueue().TaskType())
+	var taskHooks []hooks.TaskHook
+	for _, hookProducer := range taskHookFactories {


do we have a case for more than one of these? can we simplify it to one optional hook factory/hook?

We have a use case for one today, but I don't believe it is wise to limit today given all the difference is having this as a loop

dnr · 2026-02-18T22:54:08Z

 		assignedBuildId = spoolQueue.QueueKey().Version().BuildId()
 	}

+	pm.processTaskAddHooks(ctx, targetVersion, false, dbq)


what about errors? do we care if we call this and then SpoolTask fails?

Thinking about this some more. Originally, I didn't really care about errors as slight over-signaling isn't harmful for the specific use case. That said, It is likely to be confusing when debugging, and similarly under-signaling also cannot be a critical issue. So in the name of less confusion, changing it to only trigger the hooks on successful spool

jaypipes

Obviously I need to read more about how the matching service works, but I would have thought that there would be an event sink that we could set up to receive an event/signal that a particular task queue + type tuple had no active pollers. Is there no such mechanism we can "hook into"?

jaypipes · 2026-02-19T20:09:48Z

+	for _, hook := range pm.taskHooks {
+		hook.Start()
+	}


Here and below, do we need to have a deterministic order to the firing of task hook Start() and (reverse-orderered) Stop() calls?

There is no promise on ordering of different hooks, so they need to be independent in general - which should extend to start and stop

02strich · 2026-02-19T20:15:48Z

Obviously I need to read more about how the matching service works, but I would have thought that there would be an event sink that we could set up to receive an event/signal that a particular task queue + type tuple had no active pollers. Is there no such mechanism we can "hook into"?

@jaypipes this PR adds that hook point. Though we don't care about whether there are no active pollers in general, but just when a task needs to be matched so this is in the task dispatching path.

ShahabT · 2026-02-19T20:57:34Z

+		TaskQueueName string
+		TaskQueueType enumspb.TaskQueueType
+		TaskQueueKind enumspb.TaskQueueKind


I think it should be tqid.Partition to match the granularity in which we create the hook instances.

The Partition has all the info needed by the hook. I understand that the hook's usage of the data may be oblivious of the fact that it is partition level, but still the interface should be clear that instantiation is per partition.

I also have a problem with bringing TaskQueueKind to the interface, as the enum belongs to the outdated representation of sticky task queues. For context, sticky task queues are now considered a partition of the user-level task queue, and not as much of a separate task queue.

Discussed offline, and added a stripped down interface to reduce the amount of exposed details

… (or not) This adds a hook point to the matching service once it has matched a task or decided to spool it. This can be leveraged to react to task sync or no-sync match events, while keeping matching service decoupled from the event handling logic.

dnr · 2026-02-20T21:17:12Z

+	// TaskQueuePartition is a simplified version of tqid.Partition that removes details
+	// the hooks should not concern themselves with
+	TaskQueuePartition interface {
+		NamespaceId() string


could probably drop this since we have Namespace in the TaskHookFactoryCreateDetails?

dnr · 2026-02-20T21:24:14Z

+	s.Require().Eventually(func() bool {
+		select {
+		case <-pollStarted:
+			return true
+		default:
+			return false
+		}
+	}, 2*time.Second, 1*time.Millisecond)


nit: it might be nice to move https://github.com/temporalio/temporal/blob/main/tests/testcore/functional_test_base.go#L660
to a common test utils so we could use it in unit tests. doesn't have to be now of course

02strich force-pushed the stefan/matching-service branch 8 times, most recently from cb2a1fa to 30a201a Compare February 13, 2026 04:36

rkannan82 reviewed Feb 16, 2026

View reviewed changes

Comment thread service/matching/task_queue_partition_manager.go Outdated

Comment thread service/matching/task_queue_partition_manager.go Outdated

02strich force-pushed the stefan/matching-service branch from 30a201a to fa521df Compare February 17, 2026 22:16

02strich marked this pull request as ready for review February 17, 2026 22:17

02strich requested review from a team as code owners February 17, 2026 22:17