Add client-side support for JetStream message scheduling (publish options)

[Xayc73]

Problem

JetStream now supports server-side message scheduling via headers (Nats-Schedule, Nats-Schedule-Target, Nats-Schedule-TTL, Nats-Schedule-Time-Zone, etc.) and the AllowMsgSchedules stream option. The stream config field is already exposed in nats.go, but there is no client-side helper to create or cancel a schedule.

As a result, users have to set raw headers by hand and encode the pattern format themselves, e.g.:

msg := nats.NewMsg(scheduleSubject)
msg.Header.Set("Nats-Schedule", "@at "+deadline.UTC().Format(time.RFC3339))
msg.Header.Set("Nats-Schedule-Target", target)
msg.Header.Set("Nats-Schedule-TTL", "1h")
js.PublishMsg(ctx, msg)

This is error-prone and undiscoverable: the header names and pattern grammar (@at, @every, cron, timezone constraints) are not represented anywhere in the Go API, so correct usage depends on reading server internals.

Proposal

Mirror the existing WithMsgTTL pattern and add scheduling as PublishOpts, with documented header constants and a small trigger helper that hides the pattern format:

js.Publish(ctx, scheduleSubject, payload,
    jetstream.WithSchedule(jetstream.ScheduleAt(deadline)), // @at / @every / cron
    jetstream.WithScheduleTarget(target),
    jetstream.WithScheduleTTL(time.Hour),
)

Questions for discussion

• Thin PublishOpts vs a higher-level Scheduler interface (Set/Cancel)?
• Naming: WithSchedule/ScheduleAt vs WithMsgSchedule/ScheduleTimeAt.
• Is server-side message scheduling considered stable enough to expose in the client API yet?

I can make changes if we approve

[piotrpio]

Per-publish options for message scheduling were released in v1.52.0 (for jetstream package), see e.g. here: https://pkg.go.dev/github.com/nats-io/nats.go/jetstream#WithScheduleAt

So your example should work (with minor tweak):

	js.Publish(ctx, scheduleSubject, payload, jetstream.WithScheduleAt(deadline),
		jetstream.WithScheduleTarget(target),
		jetstream.WithScheduleTTL(time.Hour),
	)

Unless you're using legacy API, all scheduling features available in nats-server v2.12.0 should be exposed as publish options.

[Xayc73]

Oh! I looked for this in the issues and didn't find it. And my local version was indeed 1.51.

But this is great news!

Thanks so much for highlighting this!