pocketic

package
v0.4.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 17, 2024 License: Apache-2.0 Imports: 18 Imported by: 0

README

PocketIC Golang: A Canister Testing Library

The client requires at least version 4 of the PocketIC server.

References

List of Supported Endpoints

Supported Method Endpoint
✅ GET /status
✅ POST /blobstore
✅ GET /blobstore/{id}
✅ POST /verify_signature
✳️ GET /read_graph/{state_label}/{op_id}
✅ GET /instances/
✅ POST /instances/
✅ DELETE /instances/{id}
✅ POST /instances/{id}/read/query
✅ GET /instances/{id}/read/get_time
✅ POST /instances/{id}/read/get_cycles
✅ POST /instances/{id}/read/get_stable_memory
✅ POST /instances/{id}/read/get_subnet
✅ POST /instances/{id}/read/pub_key
✅ POST /instances/{id}/update/submit_ingress_message
✅ POST /instances/{id}/update/await_ingress_message
✅ POST /instances/{id}/update/execute_ingress_message
✅ POST /instances/{id}/update/set_time
✅ POST /instances/{id}/update/add_cycles
✅ POST /instances/{id}/update/set_stable_memory
✅ POST /instances/{id}/update/tick
⚠️ GET /instances/{id}/api/v2/status
⚠️ POST /instances/{id}/api/v2/canister/{ecid}/call
⚠️ POST /instances/{id}/api/v2/canister/{ecid}/query
⚠️ POST /instances/{id}/api/v2/canister/{ecid}/read_state
✅ POST /instances/{id}/auto_progress
✅ POST /instances/{id}/stop_progress
✅ POST /http_gateway/
✅ POST /http_gateway/{id}/stop
  • ✅ Supported
  • ✳️ Supported, but only used internally.
  • ⚠️ Supported, but only through the agent.
  • ❌ Not supported.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	DefaultSubnetSpec = SubnetSpec{
		StateConfig:       SubnetStateConfigNew{},
		InstructionConfig: SubnetInstructionConfigProduction{},
		DTSFlag:           false,
	}
	DefaultSubnetConfig = SubnetConfigSet{
		NNS: &DefaultSubnetSpec,

		Application: make([]SubnetSpec, 0),
		System:      make([]SubnetSpec, 0),
	}
)

Functions

This section is empty.

Types

type Base64EncodedBlob 

type Base64EncodedBlob []byte

Base64EncodedBlob is a byte slice that is base64 encoded when marshaled to JSON. The underlying byte slice is already decoded, so it can be used as is.

func (Base64EncodedBlob) MarshalJSON 

func (b Base64EncodedBlob) MarshalJSON() ([]byte, error)

func (Base64EncodedBlob) String 

func (b Base64EncodedBlob) String() string

String returns the base64 encoded string of the blob. NOTE: it will truncate the string if it is too long.

func (*Base64EncodedBlob) UnmarshalJSON 

func (b *Base64EncodedBlob) UnmarshalJSON(bytes []byte) error

type CanisterIDRange 

type CanisterIDRange struct {
	Start principal.Principal
	End   principal.Principal
}

func (CanisterIDRange) MarshalJSON 

func (c CanisterIDRange) MarshalJSON() ([]byte, error)

func (*CanisterIDRange) UnmarshalJSON 

func (c *CanisterIDRange) UnmarshalJSON(bytes []byte) error

type Config 

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

type CreateHttpGatewayResponse 

type CreateHttpGatewayResponse struct {
	Created *HttpGatewayInfo `json:"Created,omitempty"`
	Error   *ErrorMessage    `json:"Error,omitempty"`
}

type DTSFlag 

type DTSFlag bool

func (DTSFlag) MarshalJSON 

func (f DTSFlag) MarshalJSON() ([]byte, error)

func (*DTSFlag) UnmarshalJSON 

func (f *DTSFlag) UnmarshalJSON(bytes []byte) error

type EffectivePrincipal added in v0.4.4 

type EffectivePrincipal interface {
	// contains filtered or unexported methods
}

type EffectivePrincipalCanisterID added in v0.4.4 

type EffectivePrincipalCanisterID struct {
	CanisterID Base64EncodedBlob `json:"CanisterId"`
}

type EffectivePrincipalNone added in v0.4.4 

type EffectivePrincipalNone struct{}

func (EffectivePrincipalNone) MarshalJSON added in v0.4.4 

func (n EffectivePrincipalNone) MarshalJSON() ([]byte, error)

func (EffectivePrincipalNone) UnmarshalJSON added in v0.4.4 

func (n EffectivePrincipalNone) UnmarshalJSON(bytes []byte) error

type EffectivePrincipalSubnetID added in v0.4.4 

type EffectivePrincipalSubnetID struct {
	SubnetID Base64EncodedBlob `json:"SubnetId"`
}

type ErrorMessage 

type ErrorMessage struct {
	Message string `json:"message"`
}

func (ErrorMessage) Error 

func (e ErrorMessage) Error() string

type HttpGatewayBackend 

type HttpGatewayBackend interface {
	// contains filtered or unexported methods
}

type HttpGatewayBackendPocketICInstance 

type HttpGatewayBackendPocketICInstance struct {
	PocketIcInstance int `json:"PocketIcInstance"`
}

type HttpGatewayBackendReplica 

type HttpGatewayBackendReplica struct {
	Replica string `json:"Replica"`
}

type HttpGatewayConfig 

type HttpGatewayConfig struct {
	ListenAt  *int               `json:"listen_at,omitempty"`
	ForwardTo HttpGatewayBackend `json:"forward_to"`
}

func (*HttpGatewayConfig) UnmarshalJSON 

func (h *HttpGatewayConfig) UnmarshalJSON(bytes []byte) error

type HttpGatewayInfo 

type HttpGatewayInfo struct {
	InstanceID int `json:"instance_id"`
	Port       int `json:"port"`
}

type InstanceConfig 

type InstanceConfig struct {
	InstanceID int                 `json:"instance_id"`
	Topology   map[string]Topology `json:"topology"`
}

type MessageID added in v0.4.4 

type MessageID struct {
	EffectivePrincipal EffectivePrincipal `json:"effective_principal"`
	MessageID          Base64EncodedBlob  `json:"message_id"`
}

func (*MessageID) UnmarshalJSON added in v0.4.4 

func (r *MessageID) UnmarshalJSON(bytes []byte) error

type None 

type None struct{}

func (None) MarshalJSON 

func (n None) MarshalJSON() ([]byte, error)

func (None) UnmarshalJSON 

func (n None) UnmarshalJSON(bytes []byte) error

type Option 

type Option func(*Config)

func WithApplicationSubnet 

func WithApplicationSubnet() Option

WithApplicationSubnet adds an empty Application subnet.

func WithBitcoinSubnet 

func WithBitcoinSubnet() Option

WithBitcoinSubnet adds an empty Bitcoin subnet.

func WithDTSFlag 

func WithDTSFlag() Option

WithDTSFlag sets the DTS flag for all subnets.

func WithFiduciarySubnet 

func WithFiduciarySubnet() Option

WithFiduciarySubnet adds an empty Fiduciary subnet.

func WithHTTPClient 

func WithHTTPClient(client *http.Client) Option

WithHTTPClient sets the HTTP client for the PocketIC client.

func WithIISubnet 

func WithIISubnet() Option

WithIISubnet adds an empty Internet Identity subnet.

func WithLogger 

func WithLogger(logger agent.Logger) Option

WithLogger sets the logger for the PocketIC client.

func WithNNSSubnet 

func WithNNSSubnet() Option

WithNNSSubnet adds an empty NNS subnet.

func WithPollingDelay 

func WithPollingDelay(delay, timeout time.Duration) Option

func WithSNSSubnet 

func WithSNSSubnet() Option

WithSNSSubnet adds an empty SNS subnet.

func WithSubnetConfigSet 

func WithSubnetConfigSet(subnetConfig SubnetConfigSet) Option

WithSubnetConfigSet sets the subnet configuration.

func WithSystemSubnet 

func WithSystemSubnet() Option

WithSystemSubnet adds an empty System subnet.

func WithTTL 

func WithTTL(ttl int) Option

WithTTL sets the time-to-live for the PocketIC server, in seconds.

type PocketIC 

type PocketIC struct {
	InstanceID int
	// contains filtered or unexported fields
}

PocketIC is a client for the local PocketIC server.

func New 

func New(opts ...Option) (*PocketIC, error)

New creates a new PocketIC client. The order of the options is important, some options may override others.

func (PocketIC) AddCycles 

func (pic PocketIC) AddCycles(canisterID principal.Principal, amount int) (int, error)

AddCycles add cycles to a canister. Returns the new balance.

func (PocketIC) AutoProgress 

func (pic PocketIC) AutoProgress() error

AutoProgress configures the IC to make progress automatically, i.e., periodically update the time of the IC to the real time and execute rounds on the subnets. Returns the URL at which `/api/v2` requests for this instance can be made.

func (PocketIC) AwaitCall 

func (pic PocketIC) AwaitCall(messageID MessageID) ([]byte, error)

AwaitCall awaits an update call submitted previously by `submit_call_with_effective_principal`.

func (PocketIC) CreateAndInstallCode added in v0.4.4 

func (pic PocketIC) CreateAndInstallCode(wasmModule []byte, arg []byte, optSender *principal.Principal) (*principal.Principal, error)

func (PocketIC) CreateCanister 

func (pic PocketIC) CreateCanister() (*principal.Principal, error)

CreateCanister creates a canister with default settings as the anonymous principal.

func (PocketIC) CreateCanisterOnSubnet 

func (pic PocketIC) CreateCanisterOnSubnet(subnetID principal.Principal, args ProvisionalCreateCanisterArgument) (*principal.Principal, error)

CreateCanisterOnSubnet creates a canister on the specified subnet with the specified settings.

func (PocketIC) CreateCanisterWithArgs 

func (pic PocketIC) CreateCanisterWithArgs(args ProvisionalCreateCanisterArgument) (*principal.Principal, error)

CreateCanisterWithArgs creates a canister with the specified settings and cycles.

func (PocketIC) CreateCanisterWithID 

func (pic PocketIC) CreateCanisterWithID(canisterID principal.Principal, args ProvisionalCreateCanisterArgument) (*principal.Principal, error)

CreateCanisterWithID creates a canister with the specified canister ID and settings.

func (PocketIC) CreateInstance 

func (pic PocketIC) CreateInstance(config SubnetConfigSet) (*InstanceConfig, error)

CreateInstance creates a new PocketIC instance.

func (PocketIC) DeleteInstance 

func (pic PocketIC) DeleteInstance(instanceID int) error

DeleteInstance deletes a PocketIC instance.

func (PocketIC) ExecuteCall 

func (pic PocketIC) ExecuteCall(
	canisterID principal.Principal,
	effectivePrincipal EffectivePrincipal,
	sender principal.Principal,
	method string,
	payload []byte,
) ([]byte, error)

ExecuteCall executes an update call on a canister.

func (PocketIC) GetBlob 

func (pic PocketIC) GetBlob(blobID []byte) ([]byte, error)

GetBlob retrieves a binary blob from the PocketIC server.

func (PocketIC) GetCycles 

func (pic PocketIC) GetCycles(canisterID principal.Principal) (int, error)

GetCycles returns the cycles of a canister.

func (PocketIC) GetInstances 

func (pic PocketIC) GetInstances() ([]string, error)

GetInstances lists all PocketIC instance availabilities.

func (PocketIC) GetStableMemory 

func (pic PocketIC) GetStableMemory(canisterID principal.Principal) ([]byte, error)

GetStableMemory returns the stable memory of a canister.

func (PocketIC) GetSubnet 

func (pic PocketIC) GetSubnet(canisterID principal.Principal) (*principal.Principal, error)

GetSubnet returns the subnet of a canister.

func (PocketIC) GetTime 

func (pic PocketIC) GetTime() (*time.Time, error)

GetTime returns the current time of the PocketIC instance.

func (PocketIC) InstallCode 

func (pic PocketIC) InstallCode(canisterID principal.Principal, wasmModule []byte, arg []byte, optSender *principal.Principal) error

InstallCode installs a canister with the specified wasm module and arguments.

func (PocketIC) InstanceURL 

func (pic PocketIC) InstanceURL() string

InstanceURL returns the URL of the PocketIC instance.

func (PocketIC) MakeDeterministic 

func (pic PocketIC) MakeDeterministic() error

MakeDeterministic makes the IC instance deterministic by stopping automatic progress (time updates and round executions) on the IC instance and stops the HTTP gateway for this IC instance.

func (PocketIC) MakeLive 

func (pic PocketIC) MakeLive(port *int) (string, error)

MakeLive creates an HTTP gateway for this IC instance listening on an optionally specified port and configures the IC instance to make progress automatically, i.e., periodically update the time of the IC to the real time and execute rounds on the subnets. Returns the URL at which `/api/v2` requests for this instance can be made.

func (PocketIC) QueryCall 

func (pic PocketIC) QueryCall(canisterID principal.Principal, sender principal.Principal, method string, args []any, ret []any) error

QueryCall executes a query call on a canister.

func (PocketIC) RootKey 

func (pic PocketIC) RootKey() ([]byte, error)

RootKey returns the root key of the NNS subnet.

func (PocketIC) SetStableMemory 

func (pic PocketIC) SetStableMemory(canisterID principal.Principal, data []byte, gzipCompression bool) error

SetStableMemory sets the stable memory of a canister.

func (PocketIC) SetTime 

func (pic PocketIC) SetTime(time time.Time) error

SetTime sets the current time of the IC, on all subnets.

func (PocketIC) Status 

func (pic PocketIC) Status() error

Status pings the PocketIC instance.

func (PocketIC) StopProgress 

func (pic PocketIC) StopProgress() error

StopProgress stops automatic progress (see `auto_progress`) on the IC.

func (PocketIC) SubmitCall 

func (pic PocketIC) SubmitCall(
	canisterID principal.Principal,
	sender principal.Principal,
	method string,
	payload []byte,
) (*MessageID, error)

SubmitCall submits an update call (without executing it immediately).

func (PocketIC) SubmitCallWithEP 

func (pic PocketIC) SubmitCallWithEP(
	canisterID principal.Principal,
	effectivePrincipal EffectivePrincipal,
	sender principal.Principal,
	method string,
	payload []byte,
) (*MessageID, error)

SubmitCallWithEP submits an update call with a provided effective principal (without executing it immediately).

func (PocketIC) Tick 

func (pic PocketIC) Tick() error

func (PocketIC) Topology 

func (pic PocketIC) Topology() map[string]Topology

Topology returns the topology of the PocketIC instance.

func (PocketIC) UninstallCode 

func (pic PocketIC) UninstallCode(canisterID principal.Principal, optSender *principal.Principal) error

UninstallCode uninstalls a canister.

func (PocketIC) UpdateCall 

func (pic PocketIC) UpdateCall(canisterID principal.Principal, sender principal.Principal, method string, args []any, ret []any) error

UpdateCall executes an update call on a canister.

func (PocketIC) UploadBlob 

func (pic PocketIC) UploadBlob(bytes []byte, gzipCompression bool) ([]byte, error)

UploadBlob uploads and stores a binary blob to the PocketIC server.

func (PocketIC) VerifySignature 

func (pic PocketIC) VerifySignature(sig VerifyCanisterSigArg) error

VerifySignature verifies a signature.

type ProvisionalCreateCanisterArgument 

type ProvisionalCreateCanisterArgument struct {
	Settings    *ic0.CanisterSettings `ic:"settings"`
	SpecifiedID *principal.Principal  `ic:"specified_id"`
	Amount      *int                  `ic:"amount"`
}

type RawCanisterID 

type RawCanisterID struct {
	CanisterID Base64EncodedBlob `json:"canister_id"`
}

type Reject 

type Reject string

func (Reject) Error 

func (r Reject) Error() string

type SubnetConfigSet 

type SubnetConfigSet struct {
	Application []SubnetSpec `json:"application"`
	Bitcoin     *SubnetSpec  `json:"bitcoin,omitempty"`
	Fiduciary   *SubnetSpec  `json:"fiduciary,omitempty"`
	II          *SubnetSpec  `json:"ii,omitempty"`
	NNS         *SubnetSpec  `json:"nns,omitempty"`
	SNS         *SubnetSpec  `json:"sns,omitempty"`
	System      []SubnetSpec `json:"system"`
}

type SubnetID added in v0.4.4 

type SubnetID struct {
	SubnetID Base64EncodedBlob `json:"subnet_id"`
}

type SubnetInstructionConfig 

type SubnetInstructionConfig interface {
	// contains filtered or unexported methods
}

type SubnetInstructionConfigBenchmarking 

type SubnetInstructionConfigBenchmarking struct{}

SubnetInstructionConfigBenchmarking uses very high instruction limits useful for asymptotic canister benchmarking.

func (SubnetInstructionConfigBenchmarking) MarshalJSON 

func (c SubnetInstructionConfigBenchmarking) MarshalJSON() ([]byte, error)

func (SubnetInstructionConfigBenchmarking) UnmarshalJSON 

func (c SubnetInstructionConfigBenchmarking) UnmarshalJSON(bytes []byte) error

type SubnetInstructionConfigProduction 

type SubnetInstructionConfigProduction struct{}

SubnetInstructionConfigProduction uses default instruction limits as in production.

func (SubnetInstructionConfigProduction) MarshalJSON 

func (c SubnetInstructionConfigProduction) MarshalJSON() ([]byte, error)

func (SubnetInstructionConfigProduction) UnmarshalJSON 

func (c SubnetInstructionConfigProduction) UnmarshalJSON(bytes []byte) error

type SubnetKind 

type SubnetKind string
var (
	ApplicationSubnet SubnetKind = "Application"
	BitcoinSubnet     SubnetKind = "Bitcoin"
	FiduciarySubnet   SubnetKind = "Fiduciary"
	IISubnet          SubnetKind = "II"
	NNSSubnet         SubnetKind = "NNS"
	SNSSubnet         SubnetKind = "SNS"
	SystemSubnet      SubnetKind = "System"
)

type SubnetSpec 

type SubnetSpec struct {
	StateConfig       SubnetStateConfig       `json:"state_config"`
	InstructionConfig SubnetInstructionConfig `json:"instruction_config"`
	DTSFlag           DTSFlag                 `json:"dts_flag"`
}

SubnetSpec specifies various configurations for a subnet.

func (*SubnetSpec) WithDTSFlag 

func (s *SubnetSpec) WithDTSFlag()

WithDTSFlag sets the DTS flag, returns if the SubnetSpec is nil. Safe to call on a nil SubnetSpec.

type SubnetStateConfig 

type SubnetStateConfig interface {
	// contains filtered or unexported methods
}

type SubnetStateConfigFromPath 

type SubnetStateConfigFromPath struct {
	Path     string
	SubnetID SubnetID
}

SubnetStateConfigFromPath load existing subnet state from the given path. The path must be on a filesystem accessible to the server process.

func (SubnetStateConfigFromPath) MarshalJSON 

func (c SubnetStateConfigFromPath) MarshalJSON() ([]byte, error)

func (SubnetStateConfigFromPath) UnmarshalJSON 

func (c SubnetStateConfigFromPath) UnmarshalJSON(bytes []byte) error

type SubnetStateConfigNew 

type SubnetStateConfigNew struct{}

SubnetStateConfigNew creates new subnet with empty state.

func (SubnetStateConfigNew) MarshalJSON 

func (c SubnetStateConfigNew) MarshalJSON() ([]byte, error)

func (SubnetStateConfigNew) UnmarshalJSON 

func (c SubnetStateConfigNew) UnmarshalJSON(bytes []byte) error

type Topology 

type Topology struct {
	SubnetKind     SubnetKind        `json:"subnet_kind"`
	Size           int               `json:"size"`
	CanisterRanges []CanisterIDRange `json:"canister_ranges"`
}

type UserError 

type UserError struct {
	Code        string `json:"code"`
	Description string `json:"description"`
}

func (UserError) Error 

func (e UserError) Error() string

type VerifyCanisterSigArg added in v0.4.4 

type VerifyCanisterSigArg struct {
	Message    Base64EncodedBlob `json:"msg"`
	PublicKey  Base64EncodedBlob `json:"pubkey"`
	RootPubKey Base64EncodedBlob `json:"root_pubkey"`
	Signature  Base64EncodedBlob `json:"sig"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.