wrenn/sandbox
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add minimal control plane with REST API, database, and reconciler

Browse Source 
- REST API (chi router): sandbox CRUD, exec, pause/resume, file write/read
- PostgreSQL persistence via pgx/v5 + sqlc (sandboxes table with goose migration)
- Connect RPC client to host agent for all VM operations
- Reconciler syncs host agent state with DB every 30s (detects TTL-reaped sandboxes)
- OpenAPI 3.1 spec served at /openapi.yaml, Swagger UI at /docs
- Added WriteFile/ReadFile RPCs to hostagent proto and implementations
- File upload via multipart form, download via JSON body POST
- sandbox_id propagated from control plane to host agent on create
This commit is contained in:
Rafeed M. Bhuiyan
2026-03-10 16:50:12 +06:00
parent d7b25b0891
commit ec3360d9ad
46 changed files with 2210 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

253
proto/hostagent/gen/hostagent.pb.go
View File

@ -23,6 +23,8 @@ const (
type CreateSandboxRequest struct {
state protoimpl.MessageState `protogen:"open.v1"`
// Sandbox ID assigned by the control plane. If empty, the host agent generates one.
SandboxId string `protobuf:"bytes,5,opt,name=sandbox_id,json=sandboxId,proto3" json:"sandbox_id,omitempty"`
// Template name (e.g., "minimal", "python311"). Determines base rootfs.
Template string `protobuf:"bytes,1,opt,name=template,proto3" json:"template,omitempty"`
// Number of virtual CPUs (default: 1).
@ -66,6 +68,13 @@ func (*CreateSandboxRequest) Descriptor() ([]byte, []int) {
return file_hostagent_proto_rawDescGZIP(), []int{0}
}
func (x *CreateSandboxRequest) GetSandboxId() string {
if x != nil {
return x.SandboxId
}
return ""
}
func (x *CreateSandboxRequest) GetTemplate() string {
if x != nil {
return x.Template
@ -711,12 +720,206 @@ func (x *SandboxInfo) GetTimeoutSec() int32 {
return 0
}
type WriteFileRequest struct {
state protoimpl.MessageState `protogen:"open.v1"`
SandboxId string `protobuf:"bytes,1,opt,name=sandbox_id,json=sandboxId,proto3" json:"sandbox_id,omitempty"`
Path string `protobuf:"bytes,2,opt,name=path,proto3" json:"path,omitempty"`
Content []byte `protobuf:"bytes,3,opt,name=content,proto3" json:"content,omitempty"`
unknownFields protoimpl.UnknownFields
sizeCache protoimpl.SizeCache
}
func (x *WriteFileRequest) Reset() {
*x = WriteFileRequest{}
mi := &file_hostagent_proto_msgTypes[13]
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
ms.StoreMessageInfo(mi)
}
func (x *WriteFileRequest) String() string {
return protoimpl.X.MessageStringOf(x)
}
func (*WriteFileRequest) ProtoMessage() {}
func (x *WriteFileRequest) ProtoReflect() protoreflect.Message {
mi := &file_hostagent_proto_msgTypes[13]
if x != nil {
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
if ms.LoadMessageInfo() == nil {
ms.StoreMessageInfo(mi)
}
return ms
}
return mi.MessageOf(x)
}
// Deprecated: Use WriteFileRequest.ProtoReflect.Descriptor instead.
func (*WriteFileRequest) Descriptor() ([]byte, []int) {
return file_hostagent_proto_rawDescGZIP(), []int{13}
}
func (x *WriteFileRequest) GetSandboxId() string {
if x != nil {
return x.SandboxId
}
return ""
}
func (x *WriteFileRequest) GetPath() string {
if x != nil {
return x.Path
}
return ""
}
func (x *WriteFileRequest) GetContent() []byte {
if x != nil {
return x.Content
}
return nil
}
type WriteFileResponse struct {
state protoimpl.MessageState `protogen:"open.v1"`
unknownFields protoimpl.UnknownFields
sizeCache protoimpl.SizeCache
}
func (x *WriteFileResponse) Reset() {
*x = WriteFileResponse{}
mi := &file_hostagent_proto_msgTypes[14]
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
ms.StoreMessageInfo(mi)
}
func (x *WriteFileResponse) String() string {
return protoimpl.X.MessageStringOf(x)
}
func (*WriteFileResponse) ProtoMessage() {}
func (x *WriteFileResponse) ProtoReflect() protoreflect.Message {
mi := &file_hostagent_proto_msgTypes[14]
if x != nil {
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
if ms.LoadMessageInfo() == nil {
ms.StoreMessageInfo(mi)
}
return ms
}
return mi.MessageOf(x)
}
// Deprecated: Use WriteFileResponse.ProtoReflect.Descriptor instead.
func (*WriteFileResponse) Descriptor() ([]byte, []int) {
return file_hostagent_proto_rawDescGZIP(), []int{14}
}
type ReadFileRequest struct {
state protoimpl.MessageState `protogen:"open.v1"`
SandboxId string `protobuf:"bytes,1,opt,name=sandbox_id,json=sandboxId,proto3" json:"sandbox_id,omitempty"`
Path string `protobuf:"bytes,2,opt,name=path,proto3" json:"path,omitempty"`
unknownFields protoimpl.UnknownFields
sizeCache protoimpl.SizeCache
}
func (x *ReadFileRequest) Reset() {
*x = ReadFileRequest{}
mi := &file_hostagent_proto_msgTypes[15]
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
ms.StoreMessageInfo(mi)
}
func (x *ReadFileRequest) String() string {
return protoimpl.X.MessageStringOf(x)
}
func (*ReadFileRequest) ProtoMessage() {}
func (x *ReadFileRequest) ProtoReflect() protoreflect.Message {
mi := &file_hostagent_proto_msgTypes[15]
if x != nil {
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
if ms.LoadMessageInfo() == nil {
ms.StoreMessageInfo(mi)
}
return ms
}
return mi.MessageOf(x)
}
// Deprecated: Use ReadFileRequest.ProtoReflect.Descriptor instead.
func (*ReadFileRequest) Descriptor() ([]byte, []int) {
return file_hostagent_proto_rawDescGZIP(), []int{15}
}
func (x *ReadFileRequest) GetSandboxId() string {
if x != nil {
return x.SandboxId
}
return ""
}
func (x *ReadFileRequest) GetPath() string {
if x != nil {
return x.Path
}
return ""
}
type ReadFileResponse struct {
state protoimpl.MessageState `protogen:"open.v1"`
Content []byte `protobuf:"bytes,1,opt,name=content,proto3" json:"content,omitempty"`
unknownFields protoimpl.UnknownFields
sizeCache protoimpl.SizeCache
}
func (x *ReadFileResponse) Reset() {
*x = ReadFileResponse{}
mi := &file_hostagent_proto_msgTypes[16]
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
ms.StoreMessageInfo(mi)
}
func (x *ReadFileResponse) String() string {
return protoimpl.X.MessageStringOf(x)
}
func (*ReadFileResponse) ProtoMessage() {}
func (x *ReadFileResponse) ProtoReflect() protoreflect.Message {
mi := &file_hostagent_proto_msgTypes[16]
if x != nil {
ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
if ms.LoadMessageInfo() == nil {
ms.StoreMessageInfo(mi)
}
return ms
}
return mi.MessageOf(x)
}
// Deprecated: Use ReadFileResponse.ProtoReflect.Descriptor instead.
func (*ReadFileResponse) Descriptor() ([]byte, []int) {
return file_hostagent_proto_rawDescGZIP(), []int{16}
}
func (x *ReadFileResponse) GetContent() []byte {
if x != nil {
return x.Content
}
return nil
}
var File_hostagent_proto protoreflect.FileDescriptor
const file_hostagent_proto_rawDesc = "" +
"\n" +
"\x0fhostagent.proto\x12\fhostagent.v1\"\x86\x01\n" +
"\x14CreateSandboxRequest\x12\x1a\n" +
"\x0fhostagent.proto\x12\fhostagent.v1\"\xa5\x01\n" +
"\x14CreateSandboxRequest\x12\x1d\n" +
"\n" +
"sandbox_id\x18\x05 \x01(\tR\tsandboxId\x12\x1a\n" +
"\btemplate\x18\x01 \x01(\tR\btemplate\x12\x14\n" +
"\x05vcpus\x18\x02 \x01(\x05R\x05vcpus\x12\x1b\n" +
"\tmemory_mb\x18\x03 \x01(\x05R\bmemoryMb\x12\x1f\n" +
@ -764,14 +967,28 @@ const file_hostagent_proto_rawDesc = "" +
"\x0fcreated_at_unix\x18\a \x01(\x03R\rcreatedAtUnix\x12-\n" +
"\x13last_active_at_unix\x18\b \x01(\x03R\x10lastActiveAtUnix\x12\x1f\n" +
"\vtimeout_sec\x18\t \x01(\x05R\n" +
"timeoutSec2\x93\x04\n" +
"timeoutSec\"_\n" +
"\x10WriteFileRequest\x12\x1d\n" +
"\n" +
"sandbox_id\x18\x01 \x01(\tR\tsandboxId\x12\x12\n" +
"\x04path\x18\x02 \x01(\tR\x04path\x12\x18\n" +
"\acontent\x18\x03 \x01(\fR\acontent\"\x13\n" +
"\x11WriteFileResponse\"D\n" +
"\x0fReadFileRequest\x12\x1d\n" +
"\n" +
"sandbox_id\x18\x01 \x01(\tR\tsandboxId\x12\x12\n" +
"\x04path\x18\x02 \x01(\tR\x04path\",\n" +
"\x10ReadFileResponse\x12\x18\n" +
"\acontent\x18\x01 \x01(\fR\acontent2\xac\x05\n" +
"\x10HostAgentService\x12X\n" +
"\rCreateSandbox\x12\".hostagent.v1.CreateSandboxRequest\x1a#.hostagent.v1.CreateSandboxResponse\x12[\n" +
"\x0eDestroySandbox\x12#.hostagent.v1.DestroySandboxRequest\x1a$.hostagent.v1.DestroySandboxResponse\x12U\n" +
"\fPauseSandbox\x12!.hostagent.v1.PauseSandboxRequest\x1a\".hostagent.v1.PauseSandboxResponse\x12X\n" +
"\rResumeSandbox\x12\".hostagent.v1.ResumeSandboxRequest\x1a#.hostagent.v1.ResumeSandboxResponse\x12=\n" +
"\x04Exec\x12\x19.hostagent.v1.ExecRequest\x1a\x1a.hostagent.v1.ExecResponse\x12X\n" +
"\rListSandboxes\x12\".hostagent.v1.ListSandboxesRequest\x1a#.hostagent.v1.ListSandboxesResponseB\xb0\x01\n" +
"\rListSandboxes\x12\".hostagent.v1.ListSandboxesRequest\x1a#.hostagent.v1.ListSandboxesResponse\x12L\n" +
"\tWriteFile\x12\x1e.hostagent.v1.WriteFileRequest\x1a\x1f.hostagent.v1.WriteFileResponse\x12I\n" +
"\bReadFile\x12\x1d.hostagent.v1.ReadFileRequest\x1a\x1e.hostagent.v1.ReadFileResponseB\xb0\x01\n" +
"\x10com.hostagent.v1B\x0eHostagentProtoP\x01Z;git.omukk.dev/wrenn/sandbox/proto/hostagent/gen;hostagentv1\xa2\x02\x03HXX\xaa\x02\fHostagent.V1\xca\x02\fHostagent\\V1\xe2\x02\x18Hostagent\\V1\\GPBMetadata\xea\x02\rHostagent::V1b\x06proto3"
var (
@ -786,7 +1003,7 @@ func file_hostagent_proto_rawDescGZIP() []byte {
return file_hostagent_proto_rawDescData
}
var file_hostagent_proto_msgTypes = make([]protoimpl.MessageInfo, 13)
var file_hostagent_proto_msgTypes = make([]protoimpl.MessageInfo, 17)
var file_hostagent_proto_goTypes = []any{
(*CreateSandboxRequest)(nil), // 0: hostagent.v1.CreateSandboxRequest
(*CreateSandboxResponse)(nil), // 1: hostagent.v1.CreateSandboxResponse
@ -801,6 +1018,10 @@ var file_hostagent_proto_goTypes = []any{
(*ListSandboxesRequest)(nil), // 10: hostagent.v1.ListSandboxesRequest
(*ListSandboxesResponse)(nil), // 11: hostagent.v1.ListSandboxesResponse
(*SandboxInfo)(nil), // 12: hostagent.v1.SandboxInfo
(*WriteFileRequest)(nil), // 13: hostagent.v1.WriteFileRequest
(*WriteFileResponse)(nil), // 14: hostagent.v1.WriteFileResponse
(*ReadFileRequest)(nil), // 15: hostagent.v1.ReadFileRequest
(*ReadFileResponse)(nil), // 16: hostagent.v1.ReadFileResponse
}
var file_hostagent_proto_depIdxs = []int32{
12, // 0: hostagent.v1.ListSandboxesResponse.sandboxes:type_name -> hostagent.v1.SandboxInfo
@ -810,14 +1031,18 @@ var file_hostagent_proto_depIdxs = []int32{
6, // 4: hostagent.v1.HostAgentService.ResumeSandbox:input_type -> hostagent.v1.ResumeSandboxRequest
8, // 5: hostagent.v1.HostAgentService.Exec:input_type -> hostagent.v1.ExecRequest
10, // 6: hostagent.v1.HostAgentService.ListSandboxes:input_type -> hostagent.v1.ListSandboxesRequest
1, // 7: hostagent.v1.HostAgentService.CreateSandbox:output_type -> hostagent.v1.CreateSandboxResponse
3, // 8: hostagent.v1.HostAgentService.DestroySandbox:output_type -> hostagent.v1.DestroySandboxResponse
5, // 9: hostagent.v1.HostAgentService.PauseSandbox:output_type -> hostagent.v1.PauseSandboxResponse
7, // 10: hostagent.v1.HostAgentService.ResumeSandbox:output_type -> hostagent.v1.ResumeSandboxResponse
9, // 11: hostagent.v1.HostAgentService.Exec:output_type -> hostagent.v1.ExecResponse
11, // 12: hostagent.v1.HostAgentService.ListSandboxes:output_type -> hostagent.v1.ListSandboxesResponse
7, // [7:13] is the sub-list for method output_type
1, // [1:7] is the sub-list for method input_type
13, // 7: hostagent.v1.HostAgentService.WriteFile:input_type -> hostagent.v1.WriteFileRequest
15, // 8: hostagent.v1.HostAgentService.ReadFile:input_type -> hostagent.v1.ReadFileRequest
1, // 9: hostagent.v1.HostAgentService.CreateSandbox:output_type -> hostagent.v1.CreateSandboxResponse
3, // 10: hostagent.v1.HostAgentService.DestroySandbox:output_type -> hostagent.v1.DestroySandboxResponse
5, // 11: hostagent.v1.HostAgentService.PauseSandbox:output_type -> hostagent.v1.PauseSandboxResponse
7, // 12: hostagent.v1.HostAgentService.ResumeSandbox:output_type -> hostagent.v1.ResumeSandboxResponse
9, // 13: hostagent.v1.HostAgentService.Exec:output_type -> hostagent.v1.ExecResponse
11, // 14: hostagent.v1.HostAgentService.ListSandboxes:output_type -> hostagent.v1.ListSandboxesResponse
14, // 15: hostagent.v1.HostAgentService.WriteFile:output_type -> hostagent.v1.WriteFileResponse
16, // 16: hostagent.v1.HostAgentService.ReadFile:output_type -> hostagent.v1.ReadFileResponse
9, // [9:17] is the sub-list for method output_type
1, // [1:9] is the sub-list for method input_type
1, // [1:1] is the sub-list for extension type_name
1, // [1:1] is the sub-list for extension extendee
0, // [0:1] is the sub-list for field type_name
@ -834,7 +1059,7 @@ func file_hostagent_proto_init() {
GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
RawDescriptor: unsafe.Slice(unsafe.StringData(file_hostagent_proto_rawDesc), len(file_hostagent_proto_rawDesc)),
NumEnums: 0,
NumMessages: 13,
NumMessages: 17,
NumExtensions: 0,
NumServices: 1,
},

62
proto/hostagent/gen/hostagentv1connect/hostagent.connect.go
View File

@ -50,6 +50,12 @@ const (
// HostAgentServiceListSandboxesProcedure is the fully-qualified name of the HostAgentService's
// ListSandboxes RPC.
HostAgentServiceListSandboxesProcedure = "/hostagent.v1.HostAgentService/ListSandboxes"
// HostAgentServiceWriteFileProcedure is the fully-qualified name of the HostAgentService's
// WriteFile RPC.
HostAgentServiceWriteFileProcedure = "/hostagent.v1.HostAgentService/WriteFile"
// HostAgentServiceReadFileProcedure is the fully-qualified name of the HostAgentService's ReadFile
// RPC.
HostAgentServiceReadFileProcedure = "/hostagent.v1.HostAgentService/ReadFile"
)
// HostAgentServiceClient is a client for the hostagent.v1.HostAgentService service.
@ -66,6 +72,10 @@ type HostAgentServiceClient interface {
Exec(context.Context, *connect.Request[gen.ExecRequest]) (*connect.Response[gen.ExecResponse], error)
// ListSandboxes returns all sandboxes managed by this host agent.
ListSandboxes(context.Context, *connect.Request[gen.ListSandboxesRequest]) (*connect.Response[gen.ListSandboxesResponse], error)
// WriteFile writes content to a file inside a sandbox.
WriteFile(context.Context, *connect.Request[gen.WriteFileRequest]) (*connect.Response[gen.WriteFileResponse], error)
// ReadFile reads a file from inside a sandbox.
ReadFile(context.Context, *connect.Request[gen.ReadFileRequest]) (*connect.Response[gen.ReadFileResponse], error)
}
// NewHostAgentServiceClient constructs a client for the hostagent.v1.HostAgentService service. By
@ -115,6 +125,18 @@ func NewHostAgentServiceClient(httpClient connect.HTTPClient, baseURL string, op
connect.WithSchema(hostAgentServiceMethods.ByName("ListSandboxes")),
connect.WithClientOptions(opts...),
),
writeFile: connect.NewClient[gen.WriteFileRequest, gen.WriteFileResponse](
httpClient,
baseURL+HostAgentServiceWriteFileProcedure,
connect.WithSchema(hostAgentServiceMethods.ByName("WriteFile")),
connect.WithClientOptions(opts...),
),
readFile: connect.NewClient[gen.ReadFileRequest, gen.ReadFileResponse](
httpClient,
baseURL+HostAgentServiceReadFileProcedure,
connect.WithSchema(hostAgentServiceMethods.ByName("ReadFile")),
connect.WithClientOptions(opts...),
),
}
}
@ -126,6 +148,8 @@ type hostAgentServiceClient struct {
resumeSandbox *connect.Client[gen.ResumeSandboxRequest, gen.ResumeSandboxResponse]
exec *connect.Client[gen.ExecRequest, gen.ExecResponse]
listSandboxes *connect.Client[gen.ListSandboxesRequest, gen.ListSandboxesResponse]
writeFile *connect.Client[gen.WriteFileRequest, gen.WriteFileResponse]
readFile *connect.Client[gen.ReadFileRequest, gen.ReadFileResponse]
}
// CreateSandbox calls hostagent.v1.HostAgentService.CreateSandbox.
@ -158,6 +182,16 @@ func (c *hostAgentServiceClient) ListSandboxes(ctx context.Context, req *connect
return c.listSandboxes.CallUnary(ctx, req)
}
// WriteFile calls hostagent.v1.HostAgentService.WriteFile.
func (c *hostAgentServiceClient) WriteFile(ctx context.Context, req *connect.Request[gen.WriteFileRequest]) (*connect.Response[gen.WriteFileResponse], error) {
return c.writeFile.CallUnary(ctx, req)
}
// ReadFile calls hostagent.v1.HostAgentService.ReadFile.
func (c *hostAgentServiceClient) ReadFile(ctx context.Context, req *connect.Request[gen.ReadFileRequest]) (*connect.Response[gen.ReadFileResponse], error) {
return c.readFile.CallUnary(ctx, req)
}
// HostAgentServiceHandler is an implementation of the hostagent.v1.HostAgentService service.
type HostAgentServiceHandler interface {
// CreateSandbox boots a new microVM with the given configuration.
@ -172,6 +206,10 @@ type HostAgentServiceHandler interface {
Exec(context.Context, *connect.Request[gen.ExecRequest]) (*connect.Response[gen.ExecResponse], error)
// ListSandboxes returns all sandboxes managed by this host agent.
ListSandboxes(context.Context, *connect.Request[gen.ListSandboxesRequest]) (*connect.Response[gen.ListSandboxesResponse], error)
// WriteFile writes content to a file inside a sandbox.
WriteFile(context.Context, *connect.Request[gen.WriteFileRequest]) (*connect.Response[gen.WriteFileResponse], error)
// ReadFile reads a file from inside a sandbox.
ReadFile(context.Context, *connect.Request[gen.ReadFileRequest]) (*connect.Response[gen.ReadFileResponse], error)
}
// NewHostAgentServiceHandler builds an HTTP handler from the service implementation. It returns the
@ -217,6 +255,18 @@ func NewHostAgentServiceHandler(svc HostAgentServiceHandler, opts ...connect.Han
connect.WithSchema(hostAgentServiceMethods.ByName("ListSandboxes")),
connect.WithHandlerOptions(opts...),
)
hostAgentServiceWriteFileHandler := connect.NewUnaryHandler(
HostAgentServiceWriteFileProcedure,
svc.WriteFile,
connect.WithSchema(hostAgentServiceMethods.ByName("WriteFile")),
connect.WithHandlerOptions(opts...),
)
hostAgentServiceReadFileHandler := connect.NewUnaryHandler(
HostAgentServiceReadFileProcedure,
svc.ReadFile,
connect.WithSchema(hostAgentServiceMethods.ByName("ReadFile")),
connect.WithHandlerOptions(opts...),
)
return "/hostagent.v1.HostAgentService/", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
switch r.URL.Path {
case HostAgentServiceCreateSandboxProcedure:
@ -231,6 +281,10 @@ func NewHostAgentServiceHandler(svc HostAgentServiceHandler, opts ...connect.Han
hostAgentServiceExecHandler.ServeHTTP(w, r)
case HostAgentServiceListSandboxesProcedure:
hostAgentServiceListSandboxesHandler.ServeHTTP(w, r)
case HostAgentServiceWriteFileProcedure:
hostAgentServiceWriteFileHandler.ServeHTTP(w, r)
case HostAgentServiceReadFileProcedure:
hostAgentServiceReadFileHandler.ServeHTTP(w, r)
default:
http.NotFound(w, r)
}
@ -263,3 +317,11 @@ func (UnimplementedHostAgentServiceHandler) Exec(context.Context, *connect.Reque
func (UnimplementedHostAgentServiceHandler) ListSandboxes(context.Context, *connect.Request[gen.ListSandboxesRequest]) (*connect.Response[gen.ListSandboxesResponse], error) {
return nil, connect.NewError(connect.CodeUnimplemented, errors.New("hostagent.v1.HostAgentService.ListSandboxes is not implemented"))
}
func (UnimplementedHostAgentServiceHandler) WriteFile(context.Context, *connect.Request[gen.WriteFileRequest]) (*connect.Response[gen.WriteFileResponse], error) {
return nil, connect.NewError(connect.CodeUnimplemented, errors.New("hostagent.v1.HostAgentService.WriteFile is not implemented"))
}
func (UnimplementedHostAgentServiceHandler) ReadFile(context.Context, *connect.Request[gen.ReadFileRequest]) (*connect.Response[gen.ReadFileResponse], error) {
return nil, connect.NewError(connect.CodeUnimplemented, errors.New("hostagent.v1.HostAgentService.ReadFile is not implemented"))
}