Class: Microsandbox::FS

Inherits:
Object
  • Object
show all
Defined in:
lib/microsandbox/fs.rb

Overview

Guest filesystem operations for a running sandbox. Obtain via Sandbox#fs. All paths are paths inside the guest VM.

Instance Method Summary collapse

Constructor Details

#initialize(native) ⇒ FS

Returns a new instance of FS.



83
84
85
 
# File 'lib/microsandbox/fs.rb', line 83

def initialize(native)
  @native = native
end

Instance Method Details

#copy(src, dst) ⇒ nil

Copy a file within the guest.

Returns:

  • (nil) 


139
140
141
142
 
# File 'lib/microsandbox/fs.rb', line 139

def copy(src, dst)
  @native.fs_copy(src.to_s, dst.to_s)
  nil
end

#copy_from_host(host_path, guest_path) ⇒ nil

Copy a file from the host into the guest.

Returns:

  • (nil) 


164
165
166
167
 
# File 'lib/microsandbox/fs.rb', line 164

def copy_from_host(host_path, guest_path)
  @native.fs_copy_from_host(host_path.to_s, guest_path.to_s)
  nil
end

#copy_to_host(guest_path, host_path) ⇒ nil

Copy a file from the guest to the host.

Returns:

  • (nil) 


171
172
173
174
 
# File 'lib/microsandbox/fs.rb', line 171

def copy_to_host(guest_path, host_path)
  @native.fs_copy_to_host(guest_path.to_s, host_path.to_s)
  nil
end

#exists?(path) ⇒ Boolean

Returns whether the path exists in the guest.

Returns:

  • (Boolean) —

    whether the path exists in the guest



152
153
154
 
# File 'lib/microsandbox/fs.rb', line 152

def exists?(path)
  @native.fs_exists(path.to_s)
end

#list(path) ⇒ Array<FsEntry>

List the entries of a directory.

Returns:



112
113
114
 
# File 'lib/microsandbox/fs.rb', line 112

def list(path)
  @native.fs_list(path.to_s).map { |entry| FsEntry.new(entry) }
end

#mkdir(path) ⇒ nil

Create a directory (and any missing parents).

Returns:

  • (nil) 


118
119
120
121
 
# File 'lib/microsandbox/fs.rb', line 118

def mkdir(path)
  @native.fs_mkdir(path.to_s)
  nil
end

#read(path) ⇒ String

Read a file as raw bytes (ASCII-8BIT).

Returns:

  • (String) 


89
90
91
 
# File 'lib/microsandbox/fs.rb', line 89

def read(path)
  @native.fs_read(path.to_s)
end

#read_stream(path) ⇒ FsReadStream

Open a streaming reader over a guest file — for files too large to read into memory at once (unlike #read, which buffers the whole file).

Returns:

  • (FsReadStream) —

    an Enumerable of byte chunks (ASCII-8BIT)



179
180
181
 
# File 'lib/microsandbox/fs.rb', line 179

def read_stream(path)
  FsReadStream.new(@native.fs_read_stream(path.to_s))
end

#read_text(path) ⇒ String

Read a file as a UTF-8 string.

Returns:

  • (String) 


95
96
97
 
# File 'lib/microsandbox/fs.rb', line 95

def read_text(path)
  @native.fs_read_text(path.to_s)
end

#remove(path) ⇒ nil

Remove a single file.

Returns:

  • (nil) 


125
126
127
128
 
# File 'lib/microsandbox/fs.rb', line 125

def remove(path)
  @native.fs_remove(path.to_s)
  nil
end

#remove_dir(path) ⇒ nil

Remove a directory recursively.

Returns:

  • (nil) 


132
133
134
135
 
# File 'lib/microsandbox/fs.rb', line 132

def remove_dir(path)
  @native.fs_remove_dir(path.to_s)
  nil
end

#rename(src, dst) ⇒ nil

Rename/move a file or directory within the guest.

Returns:

  • (nil) 


146
147
148
149
 
# File 'lib/microsandbox/fs.rb', line 146

def rename(src, dst)
  @native.fs_rename(src.to_s, dst.to_s)
  nil
end

#stat(path) ⇒ FsMetadata

Stat a path.

Returns:



158
159
160
 
# File 'lib/microsandbox/fs.rb', line 158

def stat(path)
  FsMetadata.new(@native.fs_stat(path.to_s))
end

#write(path, data) ⇒ nil

Write data to a file, creating or truncating it.

Parameters:

  • data (String) —

    raw bytes to write (binary-safe; ASCII-8BIT is fine)

Returns:

  • (nil)

Raises:

  • (TypeError) —

    if data is not a String (rather than silently writing its to_s form, e.g. the inspect string of a StringIO or “42”)



104
105
106
107
108
 
# File 'lib/microsandbox/fs.rb', line 104

def write(path, data)
  bytes = Microsandbox.coerce_write_bytes(data)
  @native.fs_write(path.to_s, bytes)
  nil
end

#write_stream(path) {|sink| ... } ⇒ FsWriteSink, Object

Open a streaming writer to a guest file. With a block, the sink is yielded and closed (flushed) when the block returns.

Yield Parameters:

Returns:



187
188
189
190
191
192
193
194
195
196
 
# File 'lib/microsandbox/fs.rb', line 187

def write_stream(path)
  sink = FsWriteSink.new(@native.fs_write_stream(path.to_s))
  return sink unless block_given?

  begin
    yield sink
  ensure
    sink.close
  end
end