botstate

Documentation

Overview

Package botstate implements handling of Swarming bot state dictionary.

Index

• Constants
• type Dict
  • func Edit(d Dict, cb func(d *EditableDict) error) (Dict, error)
  • func (d Dict) Equal(another Dict) bool
  • func (d *Dict) Err() error
  • func (d *Dict) FromProperty(prop datastore.Property) error
  • func (d *Dict) MarshalJSON() ([]byte, error)
  • func (d *Dict) MustReadBool(key string) bool
  • func (d *Dict) MustReadString(key string) string
  • func (d *Dict) Read(key string, val any) error
  • func (d *Dict) ReadRaw(key string) (json.RawMessage, error)
  • func (d *Dict) String() string
  • func (d *Dict) ToProperty() (datastore.Property, error)
  • func (d *Dict) UnmarshalJSON(blob []byte) error
  • func (d *Dict) Unseal() error
• type EditableDict
  • func (d *EditableDict) Read(key string, val any) error
  • func (d *EditableDict) Write(key string, val any) error

Constants

const (
	// HandshakingKey is set to true when the bot is connecting.
	HandshakingKey = "handshaking"
	// InitialDimensionsKey carries dimensions reported when the bot is connecting.
	InitialDimensionsKey = "initial_dimensions"
	// QuarantinedKey carries a self-quarantine message or a boolean.
	QuarantinedKey = "quarantined"
	// MaintenanceKey carries a bot maintenance message.
	MaintenanceKey = "maintenance"
)

Some known bot state keys.

Types

type Dict

type Dict struct {
	// JSON is serialized JSON representation of the dict.
	JSON []byte
	// contains filtered or unexported fields
}

Dict is a lazily deserialized read-only bot state JSON dict.

It can be in three state internally:

1. Sealed. In this state it is represented exclusively by a JSON byte blob (which may or may not be valid).
2. Unsealed. In this state the dict is also accessible as a string-keyed map, allowing to read values of individual keys.
3. Broken. This happens when there's an error deserializing the JSON byte blob when unsealing it. Attempts to read keys of a broken dict will end in errors.

Reading values unseals the dict. It can also be unsealed explicitly via Unseal method.

func Edit

func Edit(d Dict, cb func(d *EditableDict) error) (Dict, error)

Edit allows to mutate the state dict inside the given callback.

Returns the final mutated dict or an error if the dict could not be serialized/deserialized or the callback returned an error.

func (Dict) Equal

func (d Dict) Equal(another Dict) bool

Equal returns true if both dicts serialize to the same JSON (ignoring formatting).

This method is used by github.com/google/go-cmp/cmp in assertions. For that reason it has to have a non-pointer receiver.

func (*Dict) Err

func (d *Dict) Err() error

Err returns an error if the state dict is broken (not a valid JSON).

func (*Dict) FromProperty

func (d *Dict) FromProperty(prop datastore.Property) error

FromProperty is a part of datastore.PropertyConverter interface.

func (*Dict) MarshalJSON

func (d *Dict) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler interface.

func (*Dict) MustReadBool

func (d *Dict) MustReadBool(key string) bool

MustReadBool reads a boolean, returning false if the key is missing or on errors.

func (*Dict) MustReadString

func (d *Dict) MustReadString(key string) string

MustReadString reads a string, returning an empty string if the key is missing or on errors.

func (*Dict) Read

func (d *Dict) Read(key string, val any) error

Read reads a value of the given key if it is present.

Doesn't change `val` and returns nil if the key is missing. Returns an error if the dict or the key value can't be deserialized.

func (*Dict) ReadRaw

func (d *Dict) ReadRaw(key string) (json.RawMessage, error)

ReadRaw returns a raw serialized value of a key or nil if the key is missing.

Returns an error if the dict can't be deserialized.

func (*Dict) String

func (d *Dict) String() string

String is used for debug-logging the dict.

func (*Dict) ToProperty

func (d *Dict) ToProperty() (datastore.Property, error)

ToProperty is a part of datastore.PropertyConverter interface.

func (*Dict) UnmarshalJSON

func (d *Dict) UnmarshalJSON(blob []byte) error

UnmarshalJSON implements json.Unmarshaler interface.

func (*Dict) Unseal

func (d *Dict) Unseal() error

Unseal deserializes the JSON blob if it hasn't been deserialized yet.

type EditableDict

type EditableDict struct {
	// contains filtered or unexported fields
}

EditableDict is an editable representation of a state dict.

func (*EditableDict) Read

func (d *EditableDict) Read(key string, val any) error

Read reads a value of the given key if it is present.

Doesn't change `val` and returns nil if the key is missing. Returns an error if the key value can't be deserialized.

func (*EditableDict) Write

func (d *EditableDict) Write(key string, val any) error

Write overwrites the value of the given key.

Returns an error if the value can't be serialized.