Documentation
¶
Overview ¶
Package jobqueue defines the host-facing contract for the job-queue capability that Vibescript exposes to scripts. The runtime wraps a *Capability with a script-visible adapter; embedders implement JobQueue (and optionally JobQueueWithRetry) to back the methods.
Example ¶
Example shows how to wire a jobqueue.Capability into a script invocation via the vibes facade and observe the enqueue dispatch.
package main
import (
"context"
"fmt"
"github.com/mgomes/vibescript/vibes"
"github.com/mgomes/vibescript/vibes/capability/jobqueue"
"github.com/mgomes/vibescript/vibes/value"
)
// stubQueue records enqueue calls for the godoc Examples. Real embedders
// would push work onto Redis, SQS, or another backing store.
type stubQueue struct{}
func (stubQueue) Enqueue(_ context.Context, job jobqueue.JobQueueJob) (value.Value, error) {
return value.NewString(job.Name), nil
}
func main() {
engine := vibes.MustNewEngine(vibes.Config{})
script, err := engine.Compile(`def run()
jobs.enqueue("send_email", { to: "alex@example.com" })
end`)
if err != nil {
fmt.Println("compile:", err)
return
}
result, err := script.Call(context.Background(), "run", nil, vibes.CallOptions{
Capabilities: []vibes.CapabilityAdapter{
vibes.MustNewJobQueueCapability("jobs", stubQueue{}),
},
})
if err != nil {
fmt.Println("call:", err)
return
}
fmt.Println(result.String())
}
Output: send_email
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Capability ¶
type Capability struct {
Name string
Queue JobQueue
Retry JobQueueWithRetry
}
Capability binds a host JobQueue implementation under a script-visible name. The vibes package wraps it in a CapabilityAdapter; embedders construct one via NewCapability.
func MustNewCapability ¶
func MustNewCapability(name string, queue JobQueue) *Capability
MustNewCapability is the panicking variant of NewCapability.
Example ¶
package main
import (
"context"
"fmt"
"github.com/mgomes/vibescript/vibes/capability/jobqueue"
"github.com/mgomes/vibescript/vibes/value"
)
// stubQueue records enqueue calls for the godoc Examples. Real embedders
// would push work onto Redis, SQS, or another backing store.
type stubQueue struct{}
func (stubQueue) Enqueue(_ context.Context, job jobqueue.JobQueueJob) (value.Value, error) {
return value.NewString(job.Name), nil
}
func main() {
cap := jobqueue.MustNewCapability("jobs", stubQueue{})
fmt.Println(cap.Name)
}
Output: jobs
func NewCapability ¶
func NewCapability(name string, queue JobQueue) (*Capability, error)
NewCapability validates the inputs and returns a bound Capability. It returns an error when name is empty or when queue is a nil implementation (typed or untyped).
Example ¶
package main
import (
"context"
"fmt"
"github.com/mgomes/vibescript/vibes/capability/jobqueue"
"github.com/mgomes/vibescript/vibes/value"
)
// stubQueue records enqueue calls for the godoc Examples. Real embedders
// would push work onto Redis, SQS, or another backing store.
type stubQueue struct{}
func (stubQueue) Enqueue(_ context.Context, job jobqueue.JobQueueJob) (value.Value, error) {
return value.NewString(job.Name), nil
}
func main() {
cap, err := jobqueue.NewCapability("jobs", stubQueue{})
if err != nil {
fmt.Println("error:", err)
return
}
fmt.Println(cap.Name, cap.HasRetry())
}
Output: jobs false
func (*Capability) HasRetry ¶
func (c *Capability) HasRetry() bool
HasRetry reports whether the bound implementation supports retry.
type JobQueueEnqueueOptions ¶
type JobQueueEnqueueOptions struct {
Delay *time.Duration
Key *string
Kwargs map[string]value.Value
}
JobQueueEnqueueOptions represents keyword arguments supplied to enqueue.
func ParseEnqueueOptions ¶
func ParseEnqueueOptions(name string, kwargs map[string]value.Value) (JobQueueEnqueueOptions, error)
ParseEnqueueOptions converts kwargs received from a script into a structured JobQueueEnqueueOptions value. It is the safe public entry point: every extra keyword is checked to be data-only (no callables) and acyclic before it is cloned into the returned options, so direct embedders cannot smuggle a runtime-only value into the host. The name is used for error messages so they line up with the script-visible capability name.
func ParseEnqueueOptionsValidated ¶ added in v0.60.0
func ParseEnqueueOptionsValidated(name string, kwargs map[string]value.Value) (JobQueueEnqueueOptions, error)
ParseEnqueueOptionsValidated is the fast path for callers that have already enforced the enqueue data-only contract on kwargs (for example the runtime adapter, which validates arguments against the capability contract before dispatching). It still parses and clones delay, key, and extra kwargs, but skips the redundant data-only/cycle walk so the option graph is not traversed twice.
type JobQueueJob ¶
type JobQueueJob struct {
Name string
Payload map[string]value.Value
Options JobQueueEnqueueOptions
}
JobQueueJob captures a job invocation from script code.
type JobQueueRetryRequest ¶
JobQueueRetryRequest captures retry invocations.
type JobQueueWithRetry ¶
type JobQueueWithRetry interface {
JobQueue
Retry(ctx context.Context, req JobQueueRetryRequest) (value.Value, error)
}
JobQueueWithRetry extends JobQueue with a retry operation.
Source Files