Azure / Azure/typespec-azure

[http-client-go] Support File to represent file input and output in request/response body Implementation

Open
#4,925 2 comments 0 reactions 1 assignee Claimed by @jhendrixMSFT View on GitHub
emitter:go feature
Dominant language
TypeScript
Stars
27
Forks
90
Avg merge
1d 22h
Merged PRs (30d)
156

Description

> Migrated from https://github.com/Azure/autorest.go/issues/1851

---

## Problem

TypeSpec defines an `Http.File` type that represents file content in HTTP request and response bodies. This type carries both the binary payload and associated metadata such as filename and content type. The `@azure-tools/typespec-client-generator-core` (TCGC) library surfaces this as a dedicated SDK type that emitters are expected to handle.

The Go emitter (`typespec-go`) does not currently recognize or handle the `File` type from TCGC. When a TypeSpec operation uses `File` as a request body parameter or response body, the emitter either falls through to a default case or produces incorrect output.

### Current Behavior

The type adapter in `packages/typespec-go/src/tcgcadapter/types.ts` maps TCGC types to Go code model types via a `kind`-based switch. It handles `bytes` (mapped to `[]byte`), `model`, `enum`, `array`, `dict`, and other built-in scalar kinds. However, it has no branch for the `File` kind, so operations that accept or return file content cannot be generated correctly.

Similarly, the client adapter in `packages/typespec-go/src/tcgcadapter/clients.ts` handles streaming request and response bodies using `io.ReadSeekCloser`, but it does not account for the additional metadata (filename, content type) that `File` provides beyond a raw byte stream.

### Impact

Any TypeSpec specification that uses `Http.File` for file upload or download operations cannot be correctly generated for Go. This blocks coverage of the `http-specs/payload/file/` test scenarios and affects service APIs that model file operations.

## Planned Changes

### 1. Type Adapter — Recognize `File` in the Type Switch

Add handling for the TCGC `File` type kind in `TypeAdapter.getWireType()` within `types.ts`. The `File` type should map to a Go struct or interface that wraps the binary content along with its metadata.

**Mapping options to evaluate:**
- Use `io.ReadSeekCloser` for the content stream (consistent with existing streaming body patterns)
- Generate a `File` struct containing `Content io.ReadSeekCloser`, `ContentType string`, and `Filename string` fields
- Alternatively, use a type from `azcore` if one exists for this purpose

### 2. Client Adapter — Handle File Bodies in Request and Response Generation

Update `ClientAdapter` in `clients.ts` to:
- Detect when a request body parameter is a `File` type and generate the appropriate request construction code (set content type from the file metadata, stream the body content)
- Detect when a response body is a `File` type and generate code to populate the file struct from the HTTP response (extract content type, content disposition headers, and stream the body)

### 3. Serialization and Content-Type Handling

- When sending a `File` body, set the `Content-Type` header from the file's content type metadata rather than defaulting to `application/json`
- Support `application/octet-stream` as the default content type for file uploads
- Support `multipart/form-data` when the file is part of a multipart request

### 4. Code Model Updates

Evaluate whether the Go code model (`codemodel.go`) needs a new type to represent `File`, or if it can be composed from existing types (`io.ReadSeekCloser` plus metadata fields).

### 5. Test Coverage

Generate and validate against the TypeSpec HTTP spec test scenarios for file operations:
```
http-specs/payload/file/
```

## Related Issues

- [Azure/typespec-cpp#557](https://github.com/Azure/typespec-cpp/issues/557) — Parallel implementation for the C++ emitter
- [Azure/autorest.go#1771](https://github.com/Azure/autorest.go/issues/1771) — CSV encoding for model properties (similar content-type handling considerations)

## References

- [TCGC Type Representation](https://azure.github.io/typespec-azure/docs/libraries/typespec-client-generator-core/guideline/) — Guideline for client emitters
- [TypeSpec HTTP Library](https://typespec.io/docs/libraries/http/reference/) — `Http.File` type definition

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.