@@ -144,6 +144,19 @@ func (r *InstanceService) Start(ctx context.Context, id string, opts ...option.R
144144 return
145145}
146146
147+ // Returns information about a path in the guest filesystem. Useful for checking if
148+ // a path exists, its type, and permissions before performing file operations.
149+ func (r * InstanceService ) Stat (ctx context.Context , id string , query InstanceStatParams , opts ... option.RequestOption ) (res * PathInfo , err error ) {
150+ opts = slices .Concat (r .Options , opts )
151+ if id == "" {
152+ err = errors .New ("missing required id parameter" )
153+ return
154+ }
155+ path := fmt .Sprintf ("instances/%s/stat" , id )
156+ err = requestconfig .ExecuteNewRequest (ctx , http .MethodGet , path , query , & res , opts ... )
157+ return
158+ }
159+
147160// Stop instance (graceful shutdown)
148161func (r * InstanceService ) Stop (ctx context.Context , id string , opts ... option.RequestOption ) (res * Instance , err error ) {
149162 opts = slices .Concat (r .Options , opts )
@@ -277,6 +290,45 @@ func (r *InstanceNetwork) UnmarshalJSON(data []byte) error {
277290 return apijson .UnmarshalRoot (data , r )
278291}
279292
293+ type PathInfo struct {
294+ // Whether the path exists
295+ Exists bool `json:"exists,required"`
296+ // Error message if stat failed (e.g., permission denied). Only set when exists is
297+ // false due to an error rather than the path not existing.
298+ Error string `json:"error,nullable"`
299+ // True if this is a directory
300+ IsDir bool `json:"is_dir"`
301+ // True if this is a regular file
302+ IsFile bool `json:"is_file"`
303+ // True if this is a symbolic link (only set when follow_links=false)
304+ IsSymlink bool `json:"is_symlink"`
305+ // Symlink target path (only set when is_symlink=true)
306+ LinkTarget string `json:"link_target,nullable"`
307+ // File mode (Unix permissions)
308+ Mode int64 `json:"mode"`
309+ // File size in bytes
310+ Size int64 `json:"size"`
311+ // JSON contains metadata for fields, check presence with [respjson.Field.Valid].
312+ JSON struct {
313+ Exists respjson.Field
314+ Error respjson.Field
315+ IsDir respjson.Field
316+ IsFile respjson.Field
317+ IsSymlink respjson.Field
318+ LinkTarget respjson.Field
319+ Mode respjson.Field
320+ Size respjson.Field
321+ ExtraFields map [string ]respjson.Field
322+ raw string
323+ } `json:"-"`
324+ }
325+
326+ // Returns the unmodified JSON received from the API
327+ func (r PathInfo ) RawJSON () string { return r .JSON .raw }
328+ func (r * PathInfo ) UnmarshalJSON (data []byte ) error {
329+ return apijson .UnmarshalRoot (data , r )
330+ }
331+
280332type VolumeMount struct {
281333 // Path where volume is mounted in the guest
282334 MountPath string `json:"mount_path,required"`
@@ -354,6 +406,8 @@ type InstanceNewParams struct {
354406 Size param.Opt [string ] `json:"size,omitzero"`
355407 // Number of virtual CPUs
356408 Vcpus param.Opt [int64 ] `json:"vcpus,omitzero"`
409+ // Device IDs or names to attach for GPU/PCI passthrough
410+ Devices []string `json:"devices,omitzero"`
357411 // Environment variables
358412 Env map [string ]string `json:"env,omitzero"`
359413 // Network configuration for the instance
@@ -422,3 +476,19 @@ const (
422476 InstanceLogsParamsSourceVmm InstanceLogsParamsSource = "vmm"
423477 InstanceLogsParamsSourceHypeman InstanceLogsParamsSource = "hypeman"
424478)
479+
480+ type InstanceStatParams struct {
481+ // Path to stat in the guest filesystem
482+ Path string `query:"path,required" json:"-"`
483+ // Follow symbolic links (like stat vs lstat)
484+ FollowLinks param.Opt [bool ] `query:"follow_links,omitzero" json:"-"`
485+ paramObj
486+ }
487+
488+ // URLQuery serializes [InstanceStatParams]'s query parameters as `url.Values`.
489+ func (r InstanceStatParams ) URLQuery () (v url.Values , err error ) {
490+ return apiquery .MarshalWithSettings (r , apiquery.QuerySettings {
491+ ArrayFormat : apiquery .ArrayQueryFormatComma ,
492+ NestedFormat : apiquery .NestedQueryFormatBrackets ,
493+ })
494+ }
0 commit comments