Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

fix(parser): normalize inline image base64 before chunk upload (#21286)

jay77721d4dd1eeb28e2
diff --git a/internal/ingestion/component/chunker/image_upload_test.go b/internal/ingestion/component/chunker/image_upload_test.go
index 21542e4a64..747081d579 100644
--- a/internal/ingestion/component/chunker/image_upload_test.go
+++ b/internal/ingestion/component/chunker/image_upload_test.go
@@ -17,6 +17,7 @@
package chunker
import (
+ "bytes"
"context"
"encoding/base64"
"fmt"
@@ -28,6 +29,7 @@ import (
"ragflow/internal/agent/runtime"
"ragflow/internal/common"
"ragflow/internal/ingestion/component/globals"
+ parserlib "ragflow/internal/parser/parser"
"gorm.io/gorm"
)
@@ -40,6 +42,63 @@ const (
// pngBase64 is a tiny 1x1 PNG payload (raw base64, no data-URL prefix).
const pngBase64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
+func TestImageUploadDecorator_ParserUnpaddedImages(t *testing.T) {
+ want, err := base64.StdEncoding.DecodeString(pngBase64)
+ if err != nil {
+ t.Fatal(err)
+ }
+ for _, format := range []string{"html", "markdown"} {
+ t.Run(format, func(t *testing.T) {
+ // The same PNG with its optional base64 padding omitted.
+ uri := "data:image/png;base64," + pngBase64[:len(pngBase64)-2]
+ var parsed parserlib.ParseResult
+ if format == "html" {
+ parsed = parserlib.NewHTMLParser().ParseWithResult(t.Context(), "image.html", []byte(`<img alt="caption" src="`+uri+`">`))
+ } else {
+ p, err := parserlib.NewMarkdownParser(parserlib.GoMarkdown)
+ if err != nil {
+ t.Fatal(err)
+ }
+ parsed = p.ParseWithResult(t.Context(), "image.md", []byte("![caption]("+uri+")"))
+ }
+ if parsed.Err != nil {
+ t.Fatal(parsed.Err)
+ }
+ var uploaded []byte
+ prev := ChunkImageUploader
+ ChunkImageUploader = func(_ context.Context, kbID, chunkID string, data []byte) (string, error) {
+ uploaded = append([]byte(nil), data...)
+ return kbID + "-" + chunkID, nil
+ }
+ t.Cleanup(func() { ChunkImageUploader = prev })
+ comp, err := NewOneChunker(nil)
+ if err != nil {
+ t.Fatal(err)
+ }
+ out, err := (&imageUploadDecorator{inner: comp}).Invoke(t.Context(), nil, map[string]any{
+ "name": "image." + format, "kb_id": testKBID, "doc_id": testDocID,
+ "output_format": "json", "json": parsed.JSON,
+ })
+ if err != nil {
+ t.Fatalf("parser image failed at chunk upload: %v", err)
+ }
+ if !bytes.Equal(uploaded, want) {
+ t.Fatalf("uploaded bytes differ from original PNG: got %d bytes, want %d", len(uploaded), len(want))
+ }
+ chunks, ok := out["chunks"].([]map[string]any)
+ if !ok || len(chunks) != 1 {
+ t.Fatalf("expected one chunk, got %#v", out)
+ }
+ if chunks[0]["img_id"] != testKBID+"-"+common.ChunkID(testDocID, "caption") {
+ t.Errorf("unexpected image reference: %v", chunks[0]["img_id"])
+ }
+ if _, ok := chunks[0]["image"]; ok {
+ t.Error("raw image retained after upload")
+ }
+ })
+ }
+}
+
// TestUploadOneImage_UploadsBytes pins the pure upload contract: it receives
// already-decoded bytes (not the raw chunk image field) plus the chunkID, and
// returns the img_id — it does NOT touch any chunk map.
diff --git a/internal/parser/parser/doc_item.go b/internal/parser/parser/doc_item.go
index 14d246515e..da131a19cc 100644
--- a/internal/parser/parser/doc_item.go
+++ b/internal/parser/parser/doc_item.go
@@ -77,7 +77,8 @@ func (t TableItem) ToMap() map[string]any {
}
// ImageItem is an embedded image. Text is the alt text, Image the data
-// URL/base64 payload (possibly empty when omitted).
+// URL/base64 payload (possibly empty when omitted). Parsers emit standard
+// base64 with padding and no CR/LF in the payload.
type ImageItem struct {
Text string
Image string
diff --git a/internal/parser/parser/html_parser.go b/internal/parser/parser/html_parser.go
index a9ebf37524..466fd5cf52 100644
--- a/internal/parser/parser/html_parser.go
+++ b/internal/parser/parser/html_parser.go
@@ -19,9 +19,7 @@ package parser
import (
"bytes"
"context"
- "encoding/base64"
"fmt"
- "io"
"strings"
"golang.org/x/net/html"
@@ -371,14 +369,15 @@ func walkHTMLLeaf(n *html.Node, w *leafWriter, out *[]map[string]any, layout str
}
if n.Data == "img" {
src := htmlAttribute(n, "src")
- if !usableHTMLImageSource(src) {
+ normalized, ok := normalizeHTMLImageSource(src)
+ if !ok {
if isHTMLDataImageSource(src) {
state.skippedInlineImages++
}
return
}
flushLeafText(w, out, layout, trim)
- appendHTMLImageItem(out, state, src, htmlAttribute(n, "alt"), "", 0, 0)
+ appendHTMLImageItem(out, state, normalized, htmlAttribute(n, "alt"), "", 0, 0)
return
}
if n.Data == "pre" || n.Data == "textarea" {
@@ -474,14 +473,15 @@ func htmlTableImages(table *html.Node) ([]htmlTableImage, int) {
column = columnCounts[row]
case "img":
src := htmlAttribute(node, "src")
- if !usableHTMLImageSource(src) {
+ normalized, ok := normalizeHTMLImageSource(src)
+ if !ok {
if isHTMLDataImageSource(src) {
skippedInlineImages++
removeHTMLImageSource(node)
}
} else {
images = append(images, htmlTableImage{
- src: src,
+ src: normalized,
alt: htmlAttribute(node, "alt"),
row: row,
column: column,
@@ -512,9 +512,6 @@ func removeHTMLImageSource(n *html.Node) {
}
func appendHTMLImageItem(out *[]map[string]any, state *htmlWalkState, src, alt, parentTableID string, row, column int) {
- if comma := strings.IndexByte(src, ','); comma > 0 && len(src) >= len("data:image/") && strings.EqualFold(src[:len("data:image/")], "data:image/") {
- src = strings.ToLower(src[:comma]) + src[comma:]
- }
state.mediaOrder++
item := map[string]any{
"text": strings.TrimSpace(alt),
@@ -530,16 +527,20 @@ func appendHTMLImageItem(out *[]map[string]any, state *htmlWalkState, src, alt,
*out = append(*out, item)
}
-func usableHTMLImageSource(src string) bool {
+func normalizeHTMLImageSource(src string) (string, bool) {
src = strings.TrimSpace(src)
if !isHTMLDataImageSource(src) {
- return false
+ return "", false
}
separator := strings.IndexByte(src, ',')
if separator <= len("data:image/") || separator > 128 || !strings.EqualFold(src[separator-len(";base64"):separator], ";base64") {
- return false
+ return "", false
+ }
+ payload, _, ok := normalizeBase64ImagePayload(src[separator+1:], maxEmbeddedImageBytes)
+ if !ok {
+ return "", false
}
- return validBase64ImagePayload(src[separator+1:], maxEmbeddedImageBytes)
+ return strings.ToLower(src[:separator+1]) + payload, true
}
func isHTMLDataImageSource(src string) bool {
@@ -548,68 +549,6 @@ func isHTMLDataImageSource(src string) bool {
return len(src) >= len(dataPrefix) && strings.EqualFold(src[:len(dataPrefix)], dataPrefix)
}
-func validBase64ImagePayload(payload string, maxDecodedBytes int) bool {
- if maxDecodedBytes < 0 {
- return false
- }
- maxEncodedBytes := base64.StdEncoding.EncodedLen(maxDecodedBytes)
- encodedBytes := 0
- for i := 0; i < len(payload); i++ {
- if payload[i] == '\r' || payload[i] == '\n' {
- continue
- }
- encodedBytes++
- if encodedBytes > maxEncodedBytes {
- return false
- }
- }
- if encodedBytes == 0 {
- return false
- }
- decodedSize, ok := base64DecodedSize(payload, encodedBytes)
- if !ok || decodedSize > int64(maxDecodedBytes) {
- return false
- }
-
- for _, encoding := range []*base64.Encoding{base64.StdEncoding, base64.RawStdEncoding} {
- decoder := base64.NewDecoder(encoding, strings.NewReader(payload))
- decodedBytes, err := io.CopyN(io.Discard, decoder, int64(maxDecodedBytes)+1)
- if decodedBytes > int64(maxDecodedBytes) {
- return false
- }
- if err == io.EOF {
- return decodedBytes > 0
- }
- }
- return false
-}
-
-func base64DecodedSize(payload string, encodedBytes int) (int64, bool) {
- padding := 0
- sawPadding := false
- for i := 0; i < len(payload); i++ {
- if payload[i] == '\r' || payload[i] == '\n' {
- continue
- }
- if payload[i] == '=' {
- sawPadding = true
- padding++
- if padding > 2 {
- return 0, false
- }
- continue
- }
- if sawPadding {
- return 0, false
- }
- }
- if encodedBytes%4 == 1 || (padding > 0 && encodedBytes%4 != 0) {
- return 0, false
- }
- decodedSize := int64(encodedBytes/4)*3 + int64(encodedBytes%4)*3/4 - int64(padding)
- return decodedSize, decodedSize >= 0
-}
-
func htmlAttribute(n *html.Node, key string) string {
for _, attr := range n.Attr {
if strings.EqualFold(attr.Key, key) {
diff --git a/internal/parser/parser/image_payload.go b/internal/parser/parser/image_payload.go
new file mode 100644
index 0000000000..478d11d24d
--- /dev/null
+++ b/internal/parser/parser/image_payload.go
@@ -0,0 +1,89 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+package parser
+
+import (
+ "encoding/base64"
+ "io"
+ "strings"
+)
+
+// normalizeBase64ImagePayload validates an external image payload within its
+// decoded byte limit and returns standard base64 with padding, no CR/LF, and
+// the decoded byte count. Validation streams into io.Discard instead of
+// allocating decoded image buffers.
+func normalizeBase64ImagePayload(payload string, maxDecodedBytes int) (string, int64, bool) {
+ if maxDecodedBytes < 0 {
+ return "", 0, false
+ }
+ encodedBytes, ok := scanBase64ImagePayload(payload, base64.StdEncoding.EncodedLen(maxDecodedBytes))
+ if !ok {
+ return "", 0, false
+ }
+ payload = strings.ReplaceAll(payload, "\r", "")
+ payload = strings.ReplaceAll(payload, "\n", "")
+ if remainder := encodedBytes % 4; remainder != 0 {
+ payload += strings.Repeat("=", 4-remainder)
+ }
+ decoder := base64.NewDecoder(base64.StdEncoding, strings.NewReader(payload))
+ decodedBytes, err := io.CopyN(io.Discard, decoder, int64(maxDecodedBytes)+1)
+ if err != io.EOF || decodedBytes == 0 || decodedBytes > int64(maxDecodedBytes) {
+ return "", 0, false
+ }
+ return payload, decodedBytes, true
+}
+
+// scanBase64ImagePayload counts the base64 characters of an image payload
+// (CR/LF excluded) and rejects a payload whose padding is malformed: '=' may
+// only appear in the final quantum, at most twice, and the character count
+// must form whole quanta.
+//
+// The padding rule is what rejects data that follows a padded quantum. Go's
+// streaming decoder only reports that when the whole payload lands in one
+// decode call, so it cannot be left to the decoder.
+func scanBase64ImagePayload(payload string, maxEncodedBytes int) (int, bool) {
+ encodedBytes := 0
+ padding := 0
+ sawPadding := false
+ for i := 0; i < len(payload); i++ {
+ if payload[i] == '\r' || payload[i] == '\n' {
+ continue
+ }
+ encodedBytes++
+ if encodedBytes > maxEncodedBytes {
+ return 0, false
+ }
+ if payload[i] == '=' {
+ sawPadding = true
+ padding++
+ if padding > 2 {
+ return 0, false
+ }
+ continue
+ }
+ if sawPadding {
+ return 0, false
+ }
+ }
+ if encodedBytes == 0 {
+ return 0, false
+ }
+ if encodedBytes%4 == 1 || (padding > 0 && encodedBytes%4 != 0) {
+ return 0, false
+ }
+ return encodedBytes, true
+}
diff --git a/internal/parser/parser/image_payload_test.go b/internal/parser/parser/image_payload_test.go
new file mode 100644
index 0000000000..9c6f5d84f1
--- /dev/null
+++ b/internal/parser/parser/image_payload_test.go
@@ -0,0 +1,101 @@
+package parser
+
+import (
+ "context"
+ "strings"
+ "testing"
+)
+
+func TestParsersNormalizeInlineImagePayload(t *testing.T) {
+ markdown, err := NewMarkdownParser(GoMarkdown)
+ if err != nil {
+ t.Fatal(err)
+ }
+ for _, tc := range []struct {
+ name, payload, want string
+ }{
+ {"padded", "YQ==", "YQ=="},
+ {"missing_two_padding", "YQ", "YQ=="},
+ {"missing_one_padding", "YWI", "YWI="},
+ {"no_padding_needed", "YWJj", "YWJj"},
+ {"line_wrapped", "YW\r\nJj", "YWJj"},
+ {"empty", "", ""},
+ {"invalid_character", "Y?==", ""},
+ {"space_inside", "Y WJj", ""},
+ {"tab_inside", "YW\tJj", ""},
+ {"partial_padding", "YQ=", ""},
+ {"excess_padding", "YQ===", ""},
+ {"padding_inside", "Y=Q=", ""},
+ {"invalid_length", "Y", ""},
+ } {
+ for _, format := range []string{"html", "html_table", "markdown"} {
+ t.Run(tc.name+"/"+format, func(t *testing.T) {
+ uri := "data:image/png;base64," + tc.payload
+ var result ParseResult
+ switch format {
+ case "html":
+ result = NewHTMLParser().ParseWithResult(context.Background(), "image.html", []byte(`<p><img alt="caption" src="`+uri+`"></p>`))
+ case "html_table":
+ result = NewHTMLParser().ParseWithResult(context.Background(), "image.html", []byte(`<table><tr><td><img alt="caption" src="`+uri+`"></td></tr></table>`))
+ case "markdown":
+ result = markdown.ParseWithResult(context.Background(), "image.md", []byte("![caption](<"+uri+">)"))
+ }
+ if result.Err != nil {
+ t.Fatal(result.Err)
+ }
+ images := 0
+ for _, item := range result.JSON {
+ image, _ := item.ToMap()["image"].(string)
+ if image == "" {
+ continue
+ }
+ images++
+ if format != "markdown" {
+ image = strings.TrimPrefix(image, "data:image/png;base64,")
+ }
+ if image != tc.want {
+ t.Errorf("image payload = %q, want %q", image, tc.want)
+ }
+ }
+ wantImages := 1
+ if tc.want == "" {
+ wantImages = 0
+ if len(result.Warnings) == 0 {
+ t.Error("rejected image should produce a parser warning")
+ }
+ }
+ if images != wantImages {
+ t.Errorf("images = %d, want %d; warnings = %v", images, wantImages, result.Warnings)
+ }
+ })
+ }
+ }
+}
+
+func TestNormalizeBase64ImagePayloadByteLimit(t *testing.T) {
+ for _, tc := range []struct {
+ name, payload string
+ limit int
+ want string
+ wantSize int64
+ }{
+ {"negative_limit", "YQ", -1, "", 0},
+ {"zero_limit", "YQ", 0, "", 0},
+ {"exact_limit_padded", "YWI=", 2, "YWI=", 2},
+ {"exact_limit_unpadded", "YWI", 2, "YWI=", 2},
+ {"exact_limit_wrapped", "YW\r\nI", 2, "YWI=", 2},
+ {"over_limit_padded", "YWI=", 1, "", 0},
+ {"over_limit_unpadded", "YWI", 1, "", 0},
+ {"over_encoded_limit", "YWJjZA==", 2, "", 0},
+ {"data_after_padding", "G0==JbjQ", 16, "", 0},
+ {"data_after_padding_long", "aMRFPqfZALtY6rw50P==Pn5d", 16, "", 0},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ got, size, ok := normalizeBase64ImagePayload(tc.payload, tc.limit)
+ if got != tc.want || ok != (tc.want != "") || size != tc.wantSize {
+ t.Errorf("normalizeBase64ImagePayload(%q, %d) = (%q, %d, %v), want (%q, %d, %v)",
+ tc.payload, tc.limit, got, size, ok, tc.want, tc.wantSize, tc.want != "")
+ }
+ })
+ }
+}
diff --git a/internal/parser/parser/markdown_parser.go b/internal/parser/parser/markdown_parser.go
index e16c41984a..1edba36d67 100644
--- a/internal/parser/parser/markdown_parser.go
+++ b/internal/parser/parser/markdown_parser.go
@@ -485,21 +485,11 @@ func walkMarkdownBlocksWithImages(ctx context.Context, doc ast.Node, out *[]map[
case !budget.reserveItem():
item["media_omitted"] = true
default:
- encoded, raw, resolved := resolveImageURL(ctx, imgURL)
+ encoded, raw, size, resolved := resolveImageURL(ctx, imgURL)
if !resolved {
unresolvedImages++
break
}
- size := len(raw)
- if raw == nil {
- encodedBytes := len(encoded) - strings.Count(encoded, "\r") - strings.Count(encoded, "\n")
- decodedSize, ok := base64DecodedSize(encoded, encodedBytes)
- if !ok {
- unresolvedImages++
- break
- }
- size = int(decodedSize)
- }
if !budget.includeReservedSize(size) {
item["media_omitted"] = true
break
@@ -554,14 +544,14 @@ func findBlockImage(n ast.Node) (string, bool) {
}
// resolveImageURL resolves a Markdown image URL to an encoded payload or raw
-// bytes.
+// bytes plus the image size in bytes.
// Supports:
-// - data:image/... URIs → validated encoded payload
+// - data:image/... URIs → validated, normalized encoded payload
// - http:// / https:// URLs → fetched (with basic SSRF filtering)
//
// Local / relative paths are not fetched (security). Returns
// exactly one of encoded and raw populated on success.
-func resolveImageURL(ctx context.Context, imageURL string) (encoded string, raw []byte, ok bool) {
+func resolveImageURL(ctx context.Context, imageURL string) (encoded string, raw []byte, size int, ok bool) {
if strings.HasPrefix(strings.ToLower(imageURL), dataURIPrefix) {
// data:image/png;base64,xxxx
idx := strings.Index(imageURL, "base64,")
@@ -569,23 +559,24 @@ func resolveImageURL(ctx context.Context, imageURL string) (encoded string, raw
idx = strings.Index(strings.ToLower(imageURL), "base64,")
}
if idx < 0 {
- return "", nil, false
+ return "", nil, 0, false
}
- encoded = imageURL[idx+len("base64,"):]
- if !validBase64ImagePayload(encoded, MaxImagePayloadBytes) {
- return "", nil, false
+ var decodedSize int64
+ encoded, decodedSize, ok = normalizeBase64ImagePayload(imageURL[idx+len("base64,"):], MaxImagePayloadBytes)
+ if !ok {
+ return "", nil, 0, false
}
- return encoded, nil, true
+ return encoded, nil, int(decodedSize), true
}
if strings.HasPrefix(imageURL, "http://") || strings.HasPrefix(imageURL, "https://") {
raw, err := fetchImage(ctx, imageURL)
if err != nil {
- return "", nil, false
+ return "", nil, 0, false
}
- return "", raw, true
+ return "", raw, len(raw), true
}
// Local / relative paths — not fetched for security.
- return "", nil, false
+ return "", nil, 0, false
}
// fetchImage fetches a bounded HTTP(S) image payload. Local/private addresses
diff --git a/internal/parser/parser/markdown_parser_test.go b/internal/parser/parser/markdown_parser_test.go
index b63b101ea5..1de9e9e125 100644
--- a/internal/parser/parser/markdown_parser_test.go
+++ b/internal/parser/parser/markdown_parser_test.go
@@ -463,18 +463,21 @@ func TestMarkdownParser_FlattenMediaToText(t *testing.T) {
func TestResolveImageURL_DataURI(t *testing.T) {
b64 := base64.StdEncoding.EncodeToString([]byte("fakeimage"))
- result, raw, found := resolveImageURL(context.Background(), "data:image/png;base64,"+b64)
+ result, raw, size, found := resolveImageURL(context.Background(), "data:image/png;base64,"+b64)
if !found {
t.Fatal("expected image found for data URI")
}
if result != b64 || raw != nil {
t.Fatalf("got %q, want %q", result, b64)
}
+ if size != len("fakeimage") {
+ t.Errorf("size = %d, want %d", size, len("fakeimage"))
+ }
}
func TestResolveImageURL_LocalPathNotFetched(t *testing.T) {
// Local / relative paths are not fetched (security); resolution fails.
- if _, _, found := resolveImageURL(context.Background(), "./local/image.png"); found {
+ if _, _, _, found := resolveImageURL(context.Background(), "./local/image.png"); found {
t.Fatal("expected no image resolved for a local path")
}
}
@@ -493,13 +496,16 @@ func TestResolveImageURL_HTTPImage(t *testing.T) {
}))
defer ts.Close()
- encoded, result, found := resolveImageURL(context.Background(), ts.URL+"/image.png")
+ encoded, result, size, found := resolveImageURL(context.Background(), ts.URL+"/image.png")
if !found {
t.Fatal("expected image found for HTTP URL")
}
if encoded != "" || string(result) != "fake-png-bytes" {
t.Fatalf("got encoded=%q raw=%q, want raw image bytes", encoded, result)
}
+ if size != len("fake-png-bytes") {
+ t.Errorf("size = %d, want %d", size, len("fake-png-bytes"))
+ }
}
func TestMarkdownImageBudgetSkipsFetchAfterCountLimit(t *testing.T) {