feat(file): implement GetFile, downloads and file_unique_id

Resolve the file_unique_id stub: derive it locally from the decoded
file_id with the TDLib scheme (LE record of unique type + identifying
fields, RLE-zero encoded, base64url no padding). Web and document-family
files are exact; legacy photos use volume/local id, newer photo sources
fall back to the media id (stable per file).

Add GetFile (decode-only, no file server in the MTProto-native model),
DownloadFile (streams via the DC-migration-aware client) and
DownloadFileToPath.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: ernado

file.go

@@ -0,0 +1,164 @@
+package botapi
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/binary"
+	"io"
+
+	"github.com/gotd/td/fileid"
+)
+
+// GetFile decodes a file_id and returns a File describing it.
+//
+// Unlike the HTTP Bot API, this library is MTProto-native: there is no file
+// server, so GetFile performs no network I/O and FilePath is left empty. Use
+// DownloadFile or DownloadFileToPath to fetch the contents. FileUniqueID is
+// derived locally from the file_id.
+func (b *Bot) GetFile(_ context.Context, fileID string) (*File, error) {
+	f, err := fileid.DecodeFileID(fileID)
+	if err != nil {
+		return nil, &Error{Code: 400, Description: "Bad Request: invalid file_id"}
+	}
+	return &File{
+		FileID:       fileID,
+		FileUniqueID: fileUniqueID(f),
+	}, nil
+}
+
+// DownloadFile streams the file referenced by file_id into w. It follows DC
+// migration transparently. The number of bytes written is returned.
+func (b *Bot) DownloadFile(ctx context.Context, fileID string, w io.Writer) (int64, error) {
+	f, err := fileid.DecodeFileID(fileID)
+	if err != nil {
+		return 0, &Error{Code: 400, Description: "Bad Request: invalid file_id"}
+	}
+
+	counter := &countWriter{w: w}
+	if loc, ok := f.AsInputFileLocation(); ok {
+		if _, err := b.client.Download(loc).Stream(ctx, counter); err != nil {
+			return counter.n, asAPIError(err)
+		}
+		return counter.n, nil
+	}
+	if loc, ok := f.AsInputWebFileLocation(); ok {
+		if _, err := b.client.DownloadWeb(loc).Stream(ctx, counter); err != nil {
+			return counter.n, asAPIError(err)
+		}
+		return counter.n, nil
+	}
+	return 0, &Error{Code: 400, Description: "Bad Request: file_id is not downloadable"}
+}
+
+// DownloadFileToPath downloads the file referenced by file_id to a local path.
+func (b *Bot) DownloadFileToPath(ctx context.Context, fileID, path string) error {
+	f, err := fileid.DecodeFileID(fileID)
+	if err != nil {
+		return &Error{Code: 400, Description: "Bad Request: invalid file_id"}
+	}
+	loc, ok := f.AsInputFileLocation()
+	if !ok {
+		return &Error{Code: 400, Description: "Bad Request: file_id is not downloadable"}
+	}
+	if _, err := b.client.Download(loc).ToPath(ctx, path); err != nil {
+		return asAPIError(err)
+	}
+	return nil
+}
+
+// countWriter counts bytes forwarded to the wrapped writer.
+type countWriter struct {
+	w io.Writer
+	n int64
+}
+
+func (c *countWriter) Write(p []byte) (int, error) {
+	n, err := c.w.Write(p)
+	c.n += int64(n)
+	return n, err
+}
+
+// file_unique_id "unique types", matching the TDLib/Bot API scheme.
+const (
+	uniqueTypeWeb       = 0
+	uniqueTypePhoto     = 1
+	uniqueTypeDocument  = 2
+	uniqueTypeSecure    = 3
+	uniqueTypeEncrypted = 4
+	uniqueTypeTemp      = 5
+)
+
+// fileUniqueID derives the Bot API file_unique_id from a decoded file_id.
+//
+// It mirrors the TDLib algorithm: a little-endian record of the unique type and
+// the file's identifying fields, RLE-encoded over zero bytes and base64url
+// encoded without padding. Web and document-family files (documents, video,
+// audio, voice, stickers, animations, video notes) are exact; legacy photos use
+// their volume/local id. Newer photo-size sources that carry no volume id fall
+// back to the media id, which stays stable per file but may differ from the
+// value Telegram's own server would return.
+func fileUniqueID(f fileid.FileID) string {
+	var buf []byte
+	switch {
+	case f.URL != "":
+		buf = make([]byte, 4, 4+len(f.URL))
+		binary.LittleEndian.PutUint32(buf, uniqueTypeWeb)
+		buf = append(buf, f.URL...)
+	case isPhotoType(f.Type) && f.PhotoSizeSource.VolumeID != 0:
+		buf = make([]byte, 16)
+		binary.LittleEndian.PutUint32(buf[0:], uniqueTypePhoto)
+		binary.LittleEndian.PutUint64(buf[4:], uint64(f.PhotoSizeSource.VolumeID))
+		binary.LittleEndian.PutUint32(buf[12:], uint32(int32(f.PhotoSizeSource.LocalID)))
+	default:
+		buf = make([]byte, 12)
+		binary.LittleEndian.PutUint32(buf[0:], uint32(uniqueTypeFor(f.Type)))
+		binary.LittleEndian.PutUint64(buf[4:], uint64(f.ID))
+	}
+	return base64.RawURLEncoding.EncodeToString(rleEncode(buf))
+}
+
+func isPhotoType(t fileid.Type) bool {
+	switch t {
+	case fileid.Thumbnail, fileid.ProfilePhoto, fileid.Photo:
+		return true
+	default:
+		return false
+	}
+}
+
+func uniqueTypeFor(t fileid.Type) int {
+	switch t {
+	case fileid.Thumbnail, fileid.ProfilePhoto, fileid.Photo:
+		return uniqueTypePhoto
+	case fileid.Secure, fileid.SecureRaw:
+		return uniqueTypeSecure
+	case fileid.Encrypted, fileid.EncryptedThumbnail:
+		return uniqueTypeEncrypted
+	case fileid.Temp:
+		return uniqueTypeTemp
+	default:
+		return uniqueTypeDocument
+	}
+}
+
+// rleEncode run-length-encodes runs of zero bytes, matching the encoding TDLib
+// applies before base64url-encoding a file_unique_id. A copy of the unexported
+// helper in github.com/gotd/td/fileid.
+func rleEncode(s []byte) (r []byte) {
+	var count byte
+	for _, cur := range s {
+		if cur == 0 {
+			count++
+			continue
+		}
+		if count > 0 {
+			r = append(r, 0, count)
+			count = 0
+		}
+		r = append(r, cur)
+	}
+	if count > 0 {
+		r = append(r, 0, count)
+	}
+	return r
+}

file_test.go

@@ -0,0 +1,54 @@
+package botapi
+
+import (
+	"encoding/base64"
+	"encoding/binary"
+	"testing"
+
+	"github.com/gotd/td/fileid"
+)
+
+func TestFileUniqueID_Document(t *testing.T) {
+	f := fileid.FileID{Type: fileid.Document, ID: 0x1122334455667788}
+	got := fileUniqueID(f)
+
+	// Expected: little-endian [uint32 type=2][int64 id], RLE-zero encoded, base64url.
+	raw := make([]byte, 12)
+	binary.LittleEndian.PutUint32(raw[0:], uniqueTypeDocument)
+	binary.LittleEndian.PutUint64(raw[4:], 0x1122334455667788)
+	want := base64.RawURLEncoding.EncodeToString(rleEncode(raw))
+
+	if got != want {
+		t.Fatalf("got %q, want %q", got, want)
+	}
+	if got == "" || got == "todo" {
+		t.Fatalf("unique id not derived: %q", got)
+	}
+}
+
+func TestFileUniqueID_Web(t *testing.T) {
+	f := fileid.FileID{URL: "https://example.com/a.jpg"}
+	got := fileUniqueID(f)
+	if got == "" {
+		t.Fatal("empty unique id for web file")
+	}
+	// Different URLs must yield different unique ids.
+	other := fileUniqueID(fileid.FileID{URL: "https://example.com/b.jpg"})
+	if got == other {
+		t.Fatal("web unique ids collide across URLs")
+	}
+}
+
+func TestFileUniqueID_Stable(t *testing.T) {
+	f := fileid.FileID{Type: fileid.Video, ID: 42}
+	if a, b := fileUniqueID(f), fileUniqueID(f); a != b {
+		t.Fatalf("unstable unique id: %q vs %q", a, b)
+	}
+}
+
+func TestGetFileInvalid(t *testing.T) {
+	b := &Bot{}
+	if _, err := b.GetFile(t.Context(), "not-a-valid-file-id"); err == nil {
+		t.Fatal("expected error for invalid file_id")
+	}
+}