Documentation / guides
Session Options
Describe SessionOption values applied when rig.NewSession creates a Session.
Per-call options belong only to Rig.NewSession:
type SessionOption func(*sessionOptions) error
func (r *Rig) NewSession(
ctx context.Context,
opts ...SessionOption,
) (session.SessionController, error)
func WithSeedSnapshot(ref workspacestore.Ref) SessionOptionThe type is variadic so future session-only knobs can be added without
changing NewSession. SessionOption is not a Rig option and cannot mutate
the reusable assembly.
Seed validation
WithSeedSnapshot rejects an empty reference or a duplicate seed option. At
NewSession, the reference must resolve in the configured workspace store and
the placement must be a per-session root or an empty exclusive root. Shared
workspace placement cannot seed because concurrent owners do not provide a
stable empty target. The seed is materialized and committed before any loop
starts; the checkpoint is part of the durable session history.
live, err := runtime.NewSession(ctx, rig.WithSeedSnapshot(seedRef))
if err != nil {
var optionErr *rig.SessionOptionError
if errors.As(err, &optionErr) {
log.Println("session option refused", optionErr.Kind)
}
return err
}
defer live.Shutdown(context.Background())The returned session owns the materialized workspace. A later
CheckpointWorkspace or RestoreWorkspace is a live
session.SessionController operation, not a second SessionOption.
Ownership and failure
Options are resolved before the lifecycle allocates a session ID, lease, or
journal. A nil option returns SessionOptionNil; invalid or duplicate seeds
return *rig.SessionOptionError. If materialization, checkpoint append, or
loop construction fails, the lifecycle unwinds acquired resources and does not
return a partially live controller.