How can I schedule message?

[sheldygg]

Based on https://github.com/nats-io/nats-architecture-and-design/blob/main/adr/ADR-51.md

I created a stream:

Information for Stream test_stream created 2025-10-29 16:41:12

                Subjects: test_stream.>
                Replicas: 1
                 Storage: File

Options:

               Retention: Limits
         Acknowledgments: true
          Discard Policy: Old
        Duplicate Window: 2m0s
              Direct Get: true
    Allows Batch Publish: false
         Allows Counters: false
       Allows Msg Delete: true
  Allows Per-Message TTL: false
            Allows Purge: true
        Allows Schedules: true
          Allows Rollups: true

Limits:

        Maximum Messages: unlimited
     Maximum Per Subject: unlimited
           Maximum Bytes: unlimited
             Maximum Age: unlimited
    Maximum Message Size: unlimited
       Maximum Consumers: unlimited

State:

            Host Version: 2.12.1
      Required API Level: 2 hosted at level 2
                Messages: 0
                   Bytes: 0 B
          First Sequence: 0
           Last Sequence: 0
        Active Consumers: 0

And here's how I publish a message:

package main

import (
	"log"

	"github.com/nats-io/nats.go"
)

func main() {
	nc, err := nats.Connect(nats.DefaultURL)
	if err != nil {
		log.Fatal(err)
	}
	defer nc.Close()

	msg := nats.NewMsg("test_stream.subject")
	msg.Header.Add("Nats-Schedule", "@at 2025-10-29T23:00:00")
	msg.Header.Add("Nats-Schedule-Target", "test_stream.123")
	msg.Data = []byte("help me")
	err = nc.PublishMsg(msg)
	if err != nil {
		log.Fatal(err)
	}
}

But it immediately goes to the handler:

 nats sub 'test_stream.>'
16:49:53 Subscribing on test_stream.> 
[#1] Received on "test_stream.subject"
Nats-Schedule: @at 2025-10-29T23:00:00
Nats-Schedule-Target: test_stream.123

help me

[MauriceVanVeen]

This is intended. You just received the schedule itself which is stored on the same stream. Changing the Nats-Schedule: @at <ts> to be earlier, you'll see it gets delivered after the specified delay.

# Create the stream, allowing message scheduling.
nats str add test_stream --subjects 'test_stream.>' --defaults --allow-schedules

# In another window, start listening to the messages on the stream.
nats sub --stream test_stream

# Use JetStream publishing to know the schedule was persisted into the stream.
nats pub -J 'test_stream.subject' 'help me' -H "Nats-Schedule: @at 1970-01-01T00:00:00Z" -H "Nats-Schedule-Target: test_stream.123"

The other window has then received both messages, the schedule itself, and after the delay the delayed message:

[#1] Received JetStream message: stream: test_stream seq 1 / subject: test_stream.subject / time: 2025-10-29 17:00:36.27322331 +0100 CET
Nats-Schedule-Target: test_stream.123
Nats-Rollup: sub
Nats-Schedule: @at 1970-01-01T00:00:00Z

help me


[#2] Received JetStream message: stream: test_stream seq 2 / subject: test_stream.123 / time: 2025-10-29 17:00:36.52558582 +0100 CET
Nats-Scheduler: test_stream.subject
Nats-Schedule-Next: purge

help me

Summarizing:

• You'll need to use js.PublishMsg instead of nc.PublishMsg to know the schedule made it into the stream.
• The timestamp provided in the @at requires a time zone. Adding a Z at the end means it will be in UTC.
• Use a small delay while testing to not have to wait. Using a timestamp in the past immediately publishes.
• The stream will contain both the schedule and the delayed message. If you only want to receive the delayed message, you can use a consumer that filters on test_stream.123 instead of everything with test_stream.>.

[sheldygg]

Thank you for quick reply.