feat(api): new process, fs, and log endpoints

New endpoints for executing processes on browser instances, uploading / downloading whole directories as zip files, and streaming any log file on a browser instance

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 31
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-b55c3e0424fa7733487139488b9fff00ad8949ff02ee3160ee36b9334e84b134.yml
-openapi_spec_hash: 17f36677e3dc0a3aeb419654c8d5cae3
-config_hash: f67e4b33b2fb30c1405ee2fff8096320
+configured_endpoints: 41
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-a7c1df5070fe59642d7a1f168aa902a468227752bfc930cbf38930f7c205dbb6.yml
+openapi_spec_hash: eab65e39aef4f0a0952b82adeecf6b5b
+config_hash: 5de78bc29ac060562575cb54bb26826c

api.md

@@ -29,6 +29,8 @@ type BrowserService struct {
 	Options []option.RequestOption
 	Replays BrowserReplayService
 	Fs      BrowserFService
+	Process BrowserProcessService
+	Logs    BrowserLogService
 }
 
 // NewBrowserService generates a new service that applies the given options to each
@@ -39,6 +41,8 @@ func NewBrowserService(opts ...option.RequestOption) (r BrowserService) {
 	r.Options = opts
 	r.Replays = NewBrowserReplayService(opts...)
 	r.Fs = NewBrowserFService(opts...)
+	r.Process = NewBrowserProcessService(opts...)
+	r.Logs = NewBrowserLogService(opts...)
 	return
 }
 

browser.go

@@ -82,6 +82,19 @@ func (r *BrowserFService) DeleteFile(ctx context.Context, id string, body Browse
 	return
 }
 
+// Returns a ZIP file containing the contents of the specified directory.
+func (r *BrowserFService) DownloadDirZip(ctx context.Context, id string, query BrowserFDownloadDirZipParams, opts ...option.RequestOption) (res *http.Response, err error) {
+	opts = append(r.Options[:], opts...)
+	opts = append([]option.RequestOption{option.WithHeader("Accept", "application/zip")}, opts...)
+	if id == "" {
+		err = errors.New("missing required id parameter")
+		return
+	}
+	path := fmt.Sprintf("browsers/%s/fs/download_dir_zip", id)
+	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, query, &res, opts...)
+	return
+}
+
 // Get information about a file or directory
 func (r *BrowserFService) FileInfo(ctx context.Context, id string, query BrowserFFileInfoParams, opts ...option.RequestOption) (res *BrowserFFileInfoResponse, err error) {
 	opts = append(r.Options[:], opts...)
@@ -145,6 +158,32 @@ func (r *BrowserFService) SetFilePermissions(ctx context.Context, id string, bod
 	return
 }
 
+// Allows uploading single or multiple files to the remote filesystem.
+func (r *BrowserFService) Upload(ctx context.Context, id string, body BrowserFUploadParams, opts ...option.RequestOption) (err error) {
+	opts = append(r.Options[:], opts...)
+	opts = append([]option.RequestOption{option.WithHeader("Accept", "")}, opts...)
+	if id == "" {
+		err = errors.New("missing required id parameter")
+		return
+	}
+	path := fmt.Sprintf("browsers/%s/fs/upload", id)
+	err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, nil, opts...)
+	return
+}
+
+// Upload a zip file and extract its contents to the specified destination path.
+func (r *BrowserFService) UploadZip(ctx context.Context, id string, body BrowserFUploadZipParams, opts ...option.RequestOption) (err error) {
+	opts = append(r.Options[:], opts...)
+	opts = append([]option.RequestOption{option.WithHeader("Accept", "")}, opts...)
+	if id == "" {
+		err = errors.New("missing required id parameter")
+		return
+	}
+	path := fmt.Sprintf("browsers/%s/fs/upload_zip", id)
+	err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, nil, opts...)
+	return
+}
+
 // Write or create a file
 func (r *BrowserFService) WriteFile(ctx context.Context, id string, contents io.Reader, body BrowserFWriteFileParams, opts ...option.RequestOption) (err error) {
 	opts = append(r.Options[:], opts...)
@@ -266,6 +305,21 @@ func (r *BrowserFDeleteFileParams) UnmarshalJSON(data []byte) error {
 	return apijson.UnmarshalRoot(data, r)
 }
 
+type BrowserFDownloadDirZipParams struct {
+	// Absolute directory path to archive and download.
+	Path string `query:"path,required" json:"-"`
+	paramObj
+}
+
+// URLQuery serializes [BrowserFDownloadDirZipParams]'s query parameters as
+// `url.Values`.
+func (r BrowserFDownloadDirZipParams) URLQuery() (v url.Values, err error) {
+	return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
+		ArrayFormat:  apiquery.ArrayQueryFormatComma,
+		NestedFormat: apiquery.NestedQueryFormatBrackets,
+	})
+}
+
 type BrowserFFileInfoParams struct {
 	// Absolute path of the file or directory.
 	Path string `query:"path,required" json:"-"`
@@ -345,6 +399,70 @@ func (r *BrowserFSetFilePermissionsParams) UnmarshalJSON(data []byte) error {
 	return apijson.UnmarshalRoot(data, r)
 }
 
+type BrowserFUploadParams struct {
+	Files []BrowserFUploadParamsFile `json:"files,omitzero,required"`
+	paramObj
+}
+
+func (r BrowserFUploadParams) MarshalMultipart() (data []byte, contentType string, err error) {
+	buf := bytes.NewBuffer(nil)
+	writer := multipart.NewWriter(buf)
+	err = apiform.MarshalRoot(r, writer)
+	if err == nil {
+		err = apiform.WriteExtras(writer, r.ExtraFields())
+	}
+	if err != nil {
+		writer.Close()
+		return nil, "", err
+	}
+	err = writer.Close()
+	if err != nil {
+		return nil, "", err
+	}
+	return buf.Bytes(), writer.FormDataContentType(), nil
+}
+
+// The properties DestPath, File are required.
+type BrowserFUploadParamsFile struct {
+	// Absolute destination path to write the file.
+	DestPath string    `json:"dest_path,required"`
+	File     io.Reader `json:"file,omitzero,required" format:"binary"`
+	paramObj
+}
+
+func (r BrowserFUploadParamsFile) MarshalJSON() (data []byte, err error) {
+	type shadow BrowserFUploadParamsFile
+	return param.MarshalObject(r, (*shadow)(&r))
+}
+func (r *BrowserFUploadParamsFile) UnmarshalJSON(data []byte) error {
+	return apijson.UnmarshalRoot(data, r)
+}
+
+type BrowserFUploadZipParams struct {
+	// Absolute destination directory to extract the archive to.
+	DestPath string    `json:"dest_path,required"`
+	ZipFile  io.Reader `json:"zip_file,omitzero,required" format:"binary"`
+	paramObj
+}
+
+func (r BrowserFUploadZipParams) MarshalMultipart() (data []byte, contentType string, err error) {
+	buf := bytes.NewBuffer(nil)
+	writer := multipart.NewWriter(buf)
+	err = apiform.MarshalRoot(r, writer)
+	if err == nil {
+		err = apiform.WriteExtras(writer, r.ExtraFields())
+	}
+	if err != nil {
+		writer.Close()
+		return nil, "", err
+	}
+	err = writer.Close()
+	if err != nil {
+		return nil, "", err
+	}
+	return buf.Bytes(), writer.FormDataContentType(), nil
+}
+
 type BrowserFWriteFileParams struct {
 	// Destination absolute file path.
 	Path string `query:"path,required" json:"-"`

browserf.go

@@ -105,6 +105,46 @@ func TestBrowserFDeleteFile(t *testing.T) {
 	}
 }
 
+func TestBrowserFDownloadDirZip(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(200)
+		w.Write([]byte("abc"))
+	}))
+	defer server.Close()
+	baseURL := server.URL
+	client := kernel.NewClient(
+		option.WithBaseURL(baseURL),
+		option.WithAPIKey("My API Key"),
+	)
+	resp, err := client.Browsers.Fs.DownloadDirZip(
+		context.TODO(),
+		"id",
+		kernel.BrowserFDownloadDirZipParams{
+			Path: "/J!",
+		},
+	)
+	if err != nil {
+		var apierr *kernel.Error
+		if errors.As(err, &apierr) {
+			t.Log(string(apierr.DumpRequest(true)))
+		}
+		t.Fatalf("err should be nil: %s", err.Error())
+	}
+	defer resp.Body.Close()
+
+	b, err := io.ReadAll(resp.Body)
+	if err != nil {
+		var apierr *kernel.Error
+		if errors.As(err, &apierr) {
+			t.Log(string(apierr.DumpRequest(true)))
+		}
+		t.Fatalf("err should be nil: %s", err.Error())
+	}
+	if !bytes.Equal(b, []byte("abc")) {
+		t.Fatalf("return value not %s: %s", "abc", b)
+	}
+}
+
 func TestBrowserFFileInfo(t *testing.T) {
 	t.Skip("Prism tests are disabled")
 	baseURL := "http://localhost:4010"
@@ -265,6 +305,68 @@ func TestBrowserFSetFilePermissionsWithOptionalParams(t *testing.T) {
 	}
 }
 
+func TestBrowserFUpload(t *testing.T) {
+	t.Skip("Prism tests are disabled")
+	baseURL := "http://localhost:4010"
+	if envURL, ok := os.LookupEnv("TEST_API_BASE_URL"); ok {
+		baseURL = envURL
+	}
+	if !testutil.CheckTestServer(t, baseURL) {
+		return
+	}
+	client := kernel.NewClient(
+		option.WithBaseURL(baseURL),
+		option.WithAPIKey("My API Key"),
+	)
+	err := client.Browsers.Fs.Upload(
+		context.TODO(),
+		"id",
+		kernel.BrowserFUploadParams{
+			Files: []kernel.BrowserFUploadParamsFile{{
+				DestPath: "/J!",
+				File:     io.Reader(bytes.NewBuffer([]byte("some file contents"))),
+			}},
+		},
+	)
+	if err != nil {
+		var apierr *kernel.Error
+		if errors.As(err, &apierr) {
+			t.Log(string(apierr.DumpRequest(true)))
+		}
+		t.Fatalf("err should be nil: %s", err.Error())
+	}
+}
+
+func TestBrowserFUploadZip(t *testing.T) {
+	t.Skip("Prism tests are disabled")
+	baseURL := "http://localhost:4010"
+	if envURL, ok := os.LookupEnv("TEST_API_BASE_URL"); ok {
+		baseURL = envURL
+	}
+	if !testutil.CheckTestServer(t, baseURL) {
+		return
+	}
+	client := kernel.NewClient(
+		option.WithBaseURL(baseURL),
+		option.WithAPIKey("My API Key"),
+	)
+	err := client.Browsers.Fs.UploadZip(
+		context.TODO(),
+		"id",
+		kernel.BrowserFUploadZipParams{
+			DestPath: "/J!",
+			ZipFile:  io.Reader(bytes.NewBuffer([]byte("some file contents"))),
+		},
+	)
+	if err != nil {
+		var apierr *kernel.Error
+		if errors.As(err, &apierr) {
+			t.Log(string(apierr.DumpRequest(true)))
+		}
+		t.Fatalf("err should be nil: %s", err.Error())
+	}
+}
+
 func TestBrowserFWriteFileWithOptionalParams(t *testing.T) {
 	t.Skip("Prism tests are disabled")
 	baseURL := "http://localhost:4010"

browserf_test.go

@@ -0,0 +1,80 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+package kernel
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/url"
+
+	"github.com/onkernel/kernel-go-sdk/internal/apiquery"
+	"github.com/onkernel/kernel-go-sdk/internal/requestconfig"
+	"github.com/onkernel/kernel-go-sdk/option"
+	"github.com/onkernel/kernel-go-sdk/packages/param"
+	"github.com/onkernel/kernel-go-sdk/packages/ssestream"
+	"github.com/onkernel/kernel-go-sdk/shared"
+)
+
+// BrowserLogService contains methods and other services that help with interacting
+// with the kernel API.
+//
+// Note, unlike clients, this service does not read variables from the environment
+// automatically. You should not instantiate this service directly, and instead use
+// the [NewBrowserLogService] method instead.
+type BrowserLogService struct {
+	Options []option.RequestOption
+}
+
+// NewBrowserLogService generates a new service that applies the given options to
+// each request. These options are applied after the parent client's options (if
+// there is one), and before any request-specific options.
+func NewBrowserLogService(opts ...option.RequestOption) (r BrowserLogService) {
+	r = BrowserLogService{}
+	r.Options = opts
+	return
+}
+
+// Stream log files on the browser instance via SSE
+func (r *BrowserLogService) StreamStreaming(ctx context.Context, id string, query BrowserLogStreamParams, opts ...option.RequestOption) (stream *ssestream.Stream[shared.LogEvent]) {
+	var (
+		raw *http.Response
+		err error
+	)
+	opts = append(r.Options[:], opts...)
+	opts = append([]option.RequestOption{option.WithHeader("Accept", "text/event-stream")}, opts...)
+	if id == "" {
+		err = errors.New("missing required id parameter")
+		return
+	}
+	path := fmt.Sprintf("browsers/%s/logs/stream", id)
+	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, query, &raw, opts...)
+	return ssestream.NewStream[shared.LogEvent](ssestream.NewDecoder(raw), err)
+}
+
+type BrowserLogStreamParams struct {
+	// Any of "path", "supervisor".
+	Source BrowserLogStreamParamsSource `query:"source,omitzero,required" json:"-"`
+	Follow param.Opt[bool]              `query:"follow,omitzero" json:"-"`
+	// only required if source is path
+	Path param.Opt[string] `query:"path,omitzero" json:"-"`
+	// only required if source is supervisor
+	SupervisorProcess param.Opt[string] `query:"supervisor_process,omitzero" json:"-"`
+	paramObj
+}
+
+// URLQuery serializes [BrowserLogStreamParams]'s query parameters as `url.Values`.
+func (r BrowserLogStreamParams) URLQuery() (v url.Values, err error) {
+	return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
+		ArrayFormat:  apiquery.ArrayQueryFormatComma,
+		NestedFormat: apiquery.NestedQueryFormatBrackets,
+	})
+}
+
+type BrowserLogStreamParamsSource string
+
+const (
+	BrowserLogStreamParamsSourcePath       BrowserLogStreamParamsSource = "path"
+	BrowserLogStreamParamsSourceSupervisor BrowserLogStreamParamsSource = "supervisor"
+)