Class FakeGateway

Namespace

OpenShell.Testing

Assembly

OpenShell.Sdk.Testing.dll

The in-memory state behind one or more FakeOpenShellClient views, plus the hooks tests use to inspect calls, inject failures, script command results and drive time-dependent behaviour.

public sealed class FakeGateway : IDisposable

Inheritance

object

FakeGateway

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

All members are thread safe.

Constructors

FakeGateway(FakeGatewayOptions?)

Creates a gateway containing only the default workspace.

public FakeGateway(FakeGatewayOptions? options = null)

Parameters

options FakeGatewayOptions

Properties

ActiveListeners

The listeners created with ListenAsync(string, uint, int, ListenOptions?, CancellationToken) that have not been disposed. No socket is opened.

public IReadOnlyList<FakeListenerInfo> ActiveListeners { get; }

Property Value

IReadOnlyList<FakeListenerInfo>

Calls

A snapshot of every call recorded so far, oldest first.

public IReadOnlyList<FakeCall> Calls { get; }

Property Value

IReadOnlyList<FakeCall>

CurrentUser

Result of GetCurrentUserAsync(CancellationToken).

public CurrentUser CurrentUser { get; set; }

Property Value

CurrentUser

GatewayInfo

Result of GetGatewayInfoAsync(CancellationToken).

public GatewayInfo GatewayInfo { get; set; }

Property Value

GatewayInfo

Health

Result of CheckAsync(CancellationToken).

public HealthResult Health { get; set; }

Property Value

HealthResult

InteractiveInput

The frames interactive exec sessions have sent so far, oldest first.

public IReadOnlyList<FakeInteractiveFrame> InteractiveInput { get; }

Property Value

IReadOnlyList<FakeInteractiveFrame>

Options

The options the gateway was created with.

public FakeGatewayOptions Options { get; }

Property Value

FakeGatewayOptions

Time

The clock in use.

public TimeProvider Time { get; }

Property Value

TimeProvider

Methods

ClearCalls()

Forgets the recorded calls.

public void ClearCalls()

ClearExecHandlers()

Removes every registered exec handler.

public void ClearExecHandlers()

ClearFailures()

Removes every pending injected failure.

public void ClearFailures()

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

EmitEvent(string, string, string, string, string, string?)

Adds a platform event to a sandbox watch stream. Returns its cursor.

public string EmitEvent(string sandbox, string reason, string message, string type = "Normal", string source = "fake", string? workspace = null)

Parameters

sandbox string

reason string

message string

type string

source string

workspace string

Returns

string

EmitLog(string, string, string, string, string?)

Adds a log line to a sandbox. It reaches watchers and GetLogsAsync(string, LogOptions?, CancellationToken). Returns its cursor.

public string EmitLog(string sandbox, string message, string level = "INFO", string source = "sandbox", string? workspace = null)

Parameters

sandbox string

message string

level string

source string

workspace string

Returns

string

FailNext(string, OpenShellException, int)

Makes the next times matching calls fail with error. operation is an exact name such as Sandboxes.Create, a prefix pattern such as Sandboxes., or for every call. The failure is raised after the call is recorded.

public void FailNext(string operation, OpenShellException error, int times = 1)

Parameters

operation string

error OpenShellException

times int

GetStagedRootfs(string)

The bytes staged under a rootfs staging token, or null when the token is unknown or empty.

public byte[]? GetStagedRootfs(string stagingToken)

Parameters

stagingToken string

Returns

byte[]

ListFiles(string, string?)

The file paths stored in a sandbox, sorted.

public IReadOnlyList<string> ListFiles(string sandbox, string? workspace = null)

Parameters

sandbox string

workspace string

Returns

IReadOnlyList<string>

OnExec(Func<FakeExecInvocation, FakeExecScript?>)

Registers a handler that scripts command results. Handlers registered later run first; the first one that returns a script wins. Commands nobody scripts exit with code 0 and no output.

public void OnExec(Func<FakeExecInvocation, FakeExecScript?> handler)

Parameters

handler Func<FakeExecInvocation, FakeExecScript>

OnForward(Func<FakeForwardRequest, Stream, CancellationToken, Task>)

Replaces the handler for TCP and SSH relays. It receives the sandbox side of the connection: reading the stream yields what the client sent, and writing sends data to the client. The default handler echoes.

public void OnForward(Func<FakeForwardRequest, Stream, CancellationToken, Task> handler)

Parameters

handler Func<FakeForwardRequest, Stream, CancellationToken, Task>

ProposeChunk(string, string, NetworkPolicyRule, string, string, string, string?)

Adds a proposed network rule to a sandbox's draft policy, as the sandbox's denial analysis would. Returns the chunk id. A non-empty securityNotes marks the chunk as security flagged.

public string ProposeChunk(string sandbox, string ruleName, NetworkPolicyRule rule, string rationale = "", string securityNotes = "", string binary = "", string? workspace = null)

Parameters

sandbox string

ruleName string

rule NetworkPolicyRule

rationale string

securityNotes string

binary string

workspace string

Returns

string

PutFile(string, string, ReadOnlyMemory<byte>, string?)

Puts a file into a sandbox's in-memory file system, as if it had been uploaded.

public void PutFile(string sandbox, string remotePath, ReadOnlyMemory<byte> content, string? workspace = null)

Parameters

sandbox string

remotePath string

content ReadOnlyMemory<byte>

workspace string

ReadFile(string, string, string?)

Reads a file from a sandbox's in-memory file system; null when it does not exist.

public byte[]? ReadFile(string sandbox, string remotePath, string? workspace = null)

Parameters

sandbox string

remotePath string

workspace string

Returns

byte[]

ReportEndpointStatuses(string, IReadOnlyList<EndpointStatus>, TokenGrantFailureObservation?, string?)

Reports what the sandbox supervisor observed for its endpoints, as a real supervisor does through the gateway. Reads return the values on EndpointStatuses and LastTokenGrantFailure, and watchers see the change.

public void ReportEndpointStatuses(string sandbox, IReadOnlyList<EndpointStatus> endpointStatuses, TokenGrantFailureObservation? lastTokenGrantFailure = null, string? workspace = null)

Parameters

sandbox string

The sandbox name.

endpointStatuses IReadOnlyList<EndpointStatus>

The endpoint statuses; replaces the previous ones.

lastTokenGrantFailure TokenGrantFailureObservation

The latest token-grant failure, or null for none.

workspace string

The workspace; defaults to the gateway default workspace.

SetPendingUpdate(string, SandboxUpdate, string?)

Leaves a configuration update pending on a sandbox, as an update interrupted after the gateway admitted it does. Start and stop then fail until ResumePendingUpdateAsync(string, ulong, UpdateSandboxOptions?, CancellationToken) applies it.

public void SetPendingUpdate(string sandbox, SandboxUpdate update, string? workspace = null)

Parameters

sandbox string

The sandbox name.

update SandboxUpdate

The admitted change.

workspace string

The workspace; defaults to the gateway default workspace.

SetPhase(string, SandboxPhase, string?, int?)

Sets a sandbox phase directly and cancels any scheduled transition, so tests can reach states such as Error without waiting. Watchers see the change.

public void SetPhase(string sandbox, SandboxPhase phase, string? workspace = null, int? exitCode = null)

Parameters

sandbox string

The sandbox name.

phase SandboxPhase

The phase to pin.

workspace string

The workspace; defaults to the gateway default workspace.

exitCode int?

The main-process exit code to report, when relevant.

SetPolicyLoadStatus(string, uint, PolicyLoadStatus, string, string?)

Marks how a sandbox reported a policy revision, as the supervisor would. Use it to script failed or superseded loads.

public void SetPolicyLoadStatus(string sandbox, uint version, PolicyLoadStatus status, string error = "", string? workspace = null)

Parameters

sandbox string

version uint

status PolicyLoadStatus

error string

workspace string

SetProviderReadiness(string, ProviderReadinessState, ProviderReadinessReason)

Forces how the supervisor reports a provider mutation, for example Failed. Without an override, a mutation is ready once its sandbox is, and pending before that.

public void SetProviderReadiness(string receiptId, ProviderReadinessState state, ProviderReadinessReason reason = ProviderReadinessReason.Unspecified)

Parameters

receiptId string

The receipt id from an attach, detach or update result.

state ProviderReadinessState

The state to report. Ready and revoked must match the receipt's mutation kind.

reason ProviderReadinessReason

The reason to report with a non-complete state.