Imported from soyacen/goose (skills/go-goose/SKILL.md). Install upstream with npx skills add soyacen/goose --skill go-goose. Copyright stays with the author.

Goose HTTP/REST Code Generation Guide

This skill helps you build HTTP/REST services using the goose library. Goose generates Go server and client code from .proto files using the protoc-gen-goose plugin. It also provides a built-in upload package for handling multipart/form-data file uploads.

Proto File Structure

A goose proto file needs these elements:

syntax = "proto3";
package my.package.v1;
option go_package = "github.com/user/project/pkg/v1;pkg";

import "google/api/annotations.proto";
import "google/protobuf/wrappers.proto";

service MyService {
  rpc MyMethod(MyRequest) returns (MyResponse) {
    option (google.api.http) = {
      get: "/v1/resource/{id}"  // HTTP mapping
    };
  }
}

message MyRequest {
  int64 id = 1;
}

message MyResponse {
  string message = 1;
}

HTTP Method Mapping

Goose supports these HTTP patterns:

Path Parameters

rpc GetUser(GetUserRequest) returns (User) {
  option (google.api.http) = {
    get: "/v1/users/{id}"  // {id} maps to GetUserRequest.id
  };
}
message GetUserRequest { int64 id = 1; }

Query Strings (GET)

rpc ListUsers(ListUsersRequest) returns (UserList) {
  option (google.api.http) = {
    get: "/v1/users"  // All fields become query params
  };
}
message ListUsersRequest {
  int64 page_num = 1;
  int64 page_size = 2;
}
// GET /v1/users?page_num=1&page_size=10

Request Body

rpc CreateUser(CreateUserRequest) returns (User) {
  option (google.api.http) = {
    post: "/v1/users"
    body: "*"  // Entire request maps to body
  };
}
// POST /v1/users { "name": "Leo" }

Named Body Field

rpc UpdateUser(UpdateUserRequest) returns (User) {
  option (google.api.http) = {
    put: "/v1/users/{id}"
    body: "user"  // Only 'user' field maps to body
  };
}
message UpdateUserRequest {
  int64 id = 1;
  User user = 2;
}

Delete Method

rpc DeleteUser(DeleteUserRequest) returns (Empty) {
  option (google.api.http) = {
    delete: "/v1/users/{id}"
  };
}

Patch Method

rpc PatchUser(PatchUserRequest) returns (User) {
  option (google.api.http) = {
    patch: "/v1/users/{id}"
    body: "data"
  };
}

Response Body Patterns

// Omitted response body - response in body by default
rpc GetUser(GetUserRequest) returns (User) {
  option (google.api.http) = {
    get: "/v1/users/{id}"
  };
}

// Star response - entire response in body
rpc GetUser(GetUserRequest) returns (User) {
  option (google.api.http) = {
    get: "/v1/users/{id}"
    response_body: "*"
  };
}

// Named response body - specific field in body
rpc GetUser(GetUserRequest) returns (UserResponse) {
  option (google.api.http) = {
    get: "/v1/users/{id}"
    response_body: "data"  // Only 'data' field in response body
  };
}
message UserResponse {
  User data = 1;
  Metadata meta = 2;
}

Raw HTTP Types

// Full HTTP request/response access
rpc CustomHandler(google.rpc.HttpRequest) returns (google.rpc.HttpResponse) {
  option (google.api.http) = {
    post: "/v1/custom"
    body: "*"
  };
}

// HttpBody for file downloads
rpc Download(google.api.HttpBody) returns (google.api.HttpBody) {
  option (google.api.http) = {
    get: "/v1/download/{filename}"
  };
}

File Upload

Goose provides built-in multipart/form-data upload support via the github.com/soyacen/goose/upload package. There are three ways to define upload endpoints in proto, each mapping to a different request type.

Proto Definition

syntax = "proto3";
package my.package.v1;
option go_package = "github.com/user/project/pkg/v1;pkg";

import "google/api/annotations.proto";
import "google/api/httpbody.proto";
import "google/rpc/http.proto";

service Upload {
  // Pattern 1: Raw HttpBody — body: "*"
  // Client sends multipart/form-data directly as the request body.
  rpc Upload(google.api.HttpBody) returns (Response) {
    option (google.api.http) = {
      put: "/v1/upload/api"
      body: "*"
    };
  }

  // Pattern 2: Embedded HttpBody — body: "body"
  // HttpBody is a named field inside a wrapper message.
  rpc UploadEmbed(UploadEmbedRequest) returns (Response) {
    option (google.api.http) = {
      put: "/v1/upload/embd"
      body: "body"
    };
  }

  // Pattern 3: google.rpc.HttpRequest — body: "*"
  // Full HTTP request access including headers.
  rpc UploadForRPC(google.rpc.HttpRequest) returns (Response) {
    option (google.api.http) = {
      put: "/v1/upload/rpc"
      body: "*"
    };
  }
}

message UploadEmbedRequest {
  google.api.HttpBody body = 1;
}

message Response {
  string message = 1;
}

upload.Handler Configuration

The upload.Handler processes multipart/form-data and saves files to disk:

import "github.com/soyacen/goose/upload"

handler, err := upload.NewHandler(
    upload.WithUploadDir("./uploads"),       // Directory to save files
    upload.WithMaxFileSize(32 << 20),        // 32MB per-file limit
    upload.WithMaxTotalSize(128 << 20),      // 128MB total limit
)

Key types returned by handler.Handle():

Server Implementation

package main

import (
    "context"
    "fmt"
    "log"
    "net/http"

    "github.com/soyacen/goose/upload"
    pkg "github.com/user/project/pkg/v1"
    "google.golang.org/genproto/googleapis/api/httpbody"
    rpchttp "google.golang.org/genproto/googleapis/rpc/http"
)

type uploadService struct {
    handler *upload.Handler
}

// Pattern 1: Raw HttpBody
func (s *uploadService) Upload(ctx context.Context, req *httpbody.HttpBody) (*pkg.Response, error) {
    result, err := s.handler.Handle(req.GetData(), req.GetContentType())
    if err != nil {
        return nil, fmt.Errorf("upload failed: %w", err)
    }
    return &pkg.Response{Message: result.JSON()}, nil
}

// Pattern 2: Embedded HttpBody
func (s *uploadService) UploadEmbed(ctx context.Context, req *pkg.UploadEmbedRequest) (*pkg.Response, error) {
    body := req.GetBody()
    result, err := s.handler.Handle(body.GetData(), body.GetContentType())
    if err != nil {
        return nil, fmt.Errorf("upload failed: %w", err)
    }
    return &pkg.Response{Message: result.JSON()}, nil
}

// Pattern 3: google.rpc.HttpRequest (extract Content-Type from headers)
func (s *uploadService) UploadForRPC(ctx context.Context, req *rpchttp.HttpRequest) (*pkg.Response, error) {
    contentType := ""
    for _, h := range req.GetHeaders() {
        if h.GetKey() == "Content-Type" {
            contentType = h.GetValue()
            break
        }
    }
    result, err := s.handler.Handle(req.GetBody(), contentType)
    if err != nil {
        return nil, fmt.Errorf("upload failed: %w", err)
    }
    return &pkg.Response{Message: result.JSON()}, nil
}

func main() {
    handler, _ := upload.NewHandler(upload.WithUploadDir("./uploads"))
    router := http.NewServeMux()
    router = pkg.AppendUploadHttpRoute(router, &uploadService{handler: handler})
    log.Fatal(http.ListenAndServe(":8080", router))
}

Upload Testing

Use mime/multipart to build test request bodies:

import (
    "bytes"
    "mime/multipart"
)

func buildMultipartForm() ([]byte, string) {
    var buf bytes.Buffer
    writer := multipart.NewWriter(&buf)
    _ = writer.WriteField("name", "test_upload")
    fileWriter, _ := writer.CreateFormFile("file", "test.txt")
    _, _ = fileWriter.Write([]byte("hello file content"))
    _ = writer.Close()
    return buf.Bytes(), writer.FormDataContentType()
}

func TestUpload(t *testing.T) {
    uploadDir := t.TempDir()
    server := new(http.Server)
    defer server.Shutdown(context.Background())
    go runServer(server, 58081, uploadDir)
    time.Sleep(1 * time.Second)

    client := pkg.NewUploadHttpClient("http://localhost:58081")
    data, contentType := buildMultipartForm()
    resp, err := client.Upload(context.Background(), &httpbody.HttpBody{
        ContentType: contentType,
        Data:        data,
    })
    if err != nil {
        t.Fatal(err)
    }
    if resp.GetMessage() == "" {
        t.Fatal("resp message should not be empty")
    }
}

Generating Code

Prerequisites

go install github.com/soyacen/goose/cmd/protoc-gen-goose@latest
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

Generate Command

protoc \
  --proto_path=. \
  --proto_path=./third_party \
  --go_out=. \
  --go_opt=paths=source_relative \
  --go-grpc_out=. \
  --go-grpc_opt=paths=source_relative \
  --goose_out=. \
  --goose_opt=paths=source_relative \
  your_service.proto

Implementing the Service

Server Implementation

package main

import (
    "context"
    "log"
    "net/http"
    "github.com/soyacen/goose/example/user/v1"
    "github.com/soyacen/goose/server"
)

type userService struct{}

func (s *userService) CreateUser(ctx context.Context, req *user.CreateUserRequest) (*user.CreateUserResponse, error) {
    return &user.CreateUserResponse{
        Item: &user.UserItem{Id: 1, Name: req.Name},
    }, nil
}

func (s *userService) GetUser(ctx context.Context, req *user.GetUserRequest) (*user.GetUserResponse, error) {
    return &user.GetUserResponse{
        Item: &user.UserItem{Id: req.Id, Name: "Test"},
    }, nil
}

func main() {
    router := http.NewServeMux()
    // Generated function: Append{ServiceName}HttpRoute
    router = user.AppendUserHttpRoute(router, &userService{})

    log.Fatal(http.ListenAndServe(":8080", router))
}

Client Usage

package main

import (
    "context"
    "fmt"
    "github.com/soyacen/goose/example/user/v1"
)

func main() {
    // Generated client constructor: New{ServiceName}HttpClient
    client := user.NewUserHttpClient("http://localhost:8080")

    resp, err := client.CreateUser(context.Background(), &user.CreateUserRequest{
        Name: "Leo",
    })
    if err != nil {
        panic(err)
    }
    fmt.Printf("Created user: %v\n", resp.Item)
}

Using Middleware

Server Middleware Chain

import (
    "github.com/soyacen/goose/middleware/accesslog"
    "github.com/soyacen/goose/middleware/recovery"
    "github.com/soyacen/goose/middleware/basicauth"
    "github.com/soyacen/goose/server"
)

router := http.NewServeMux()
router = user.AppendUserHttpRoute(router, &userService{},
    server.WithMiddleware(accesslog.Server()),
    server.WithMiddleware(recovery.Server()),
    server.WithMiddleware(basicauth.Server(
        basicauth.WithCredential("admin", "secret"),
    )),
)

Available Middleware

Client Middleware

import (
    "github.com/soyacen/goose/middleware/accesslog"
    "github.com/soyacen/goose/client"
)

client := user.NewUserHttpClient("http://localhost:8080",
    client.WithMiddleware(accesslog.Client()),
)

Configuration Options

Server Options

import "github.com/soyacen/goose/server"

router = user.AppendUserHttpRoute(router, service,
    server.WithMiddleware(middleware),
    server.WithMarshalOptions(&server.MarshalOptions{
        UseJSONNames: true,
    }),
    server.WithUnmarshalOptions(&server.UnmarshalOptions{
        DiscardUnknown: true,
    }),
    server.WithErrorEncoder(myErrorEncoder),
    server.WithShouldFailFast(true),
)

Client Options

import "github.com/soyacen/goose/client"

client := user.NewUserHttpClient("http://localhost:8080",
    client.WithHTTPClient(&http.Client{Timeout: 30 * time.Second}),
    client.WithMiddleware(middleware),
    client.WithResolver(resolver),
)

Validation

Goose uses protobuf validation. Add validation rules in your proto:

message CreateUserRequest {
  string name = 1 [(validate.rules).string.min_len = 1];
  int32 age = 2 [(validate.rules).int32.gte = 0];
}

Enable validation:

server.WithShouldFailFast(true),

Testing

Example test pattern from the codebase:

func TestCreateUser(t *testing.T) {
    // Start server
    server := &http.Server{Addr: ":38080"}
    defer server.Shutdown(context.Background())

    router := http.NewServeMux()
    router = user.AppendUserHttpRoute(router, &mockService{})
    server.Handler = router

    go server.ListenAndServe()
    time.Sleep(100 * time.Millisecond) // Wait for server

    // Use client
    client := user.NewUserHttpClient("http://localhost:38080")
    resp, err := client.CreateUser(context.Background(), &user.CreateUserRequest{
        Name: "Leo",
    })
    if err != nil {
        t.Fatal(err)
    }
    if resp.Item.Name != "Leo" {
        t.Fatal("name mismatch")
    }
}

Type Support

Goose handles these protobuf types:

• Basic: bool, int32, int64, uint32, uint64, float, double, string, bytes
• Wrapper: google.protobuf.BoolValue, Int32Value, StringValue, etc.
• Optional: optional keyword (Go 1.23+)
• Repeated: slices and lists
• Enum: enum types with custom values

Project Structure

A typical goose project:

myproject/
├── proto/
│   └── service.proto
├── third_party/
│   ├── google/api/httpbody.proto
│   └── google/api/annotations.proto
├── cmd/
│   └── server/main.go
├── pkg/
│   └── service/
│       └── service.go
└── go.mod

Key Patterns

1. Service Interface: Goose generates a {Service}Service interface you must implement
2. Route Registration: Use Append{Service}HttpRoute(router, service, opts...) to register routes
3. Client Creation: Use New{Service}HttpClient(baseURL, opts...) to create clients
4. Middleware Chain: Use server.Chain(m1, m2, ...) or server.WithMiddleware() options
5. Error Handling: Custom error encoder via server.WithErrorEncoder()
6. File Upload: Use upload.Handler from github.com/soyacen/goose/upload with google.api.HttpBody or google.rpc.HttpRequest as the proto request type; pass req.GetData() and req.GetContentType() to handler.Handle()

References

• Repository: https://github.com/soyacen/goose
• Examples: example/ directory in the repository contains working examples for body, path, query, response_body, and upload patterns
• Upload: example/upload/ demonstrates multipart/form-data file upload with three proto patterns (HttpBody, embedded HttpBody, HttpRequest)