Bound PDF processing and reuse parsed render documents

Author: KSemenenko

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to ManagedCode.FileContext are documented here.
 
+## 1.0.12
+
+- Bound native PDF reads and rendering before source buffering through a shared, configurable PDF processor.
+- Expose a disposable render document with page count and sequential page rendering from one parse.
+
 ## 1.0.11
 
 - Bind and validate FileContext limits through `IOptions<FileContextOptions>`, including keyed registrations and host configuration.

Directory.Build.props

@@ -12,7 +12,7 @@
     <AnalysisMode>Recommended</AnalysisMode>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
     <NoWarn>$(NoWarn);CS1591;MAAI001</NoWarn>
-    <Version>1.0.11</Version>
+    <Version>1.0.12</Version>
     <PackageVersion>$(Version)</PackageVersion>
   </PropertyGroup>
 

docs/Architecture.md

@@ -77,6 +77,11 @@ flowchart TD
 
 ## Operational limits
 
+PDF callers share `FileContextPdfProcessor`, acquiring a permit before reading or downloading the
+source and retaining it through parsing/rendering. `MaximumConcurrentPdfOperations` defaults to one.
+`FileContextPdfRenderDocument` exposes page count and sequential page rendering from one parsed PDF;
+dispose it after the batch. The low-level synchronous image helpers remain caller-scheduled APIs.
+
 All potentially large operations are controlled by `IOptions<FileContextOptions>`: PDF source/page/image budgets, full-read bytes, range bytes, files scanned, bytes per searched file, matches per file, total search results, graph documents, graph source bytes, and exported graph characters. Non-seekable cloud streams are supported by sequential streaming.
 
 ## Start here

src/ManagedCode.FileContext/FileContextDefaults.cs

@@ -7,6 +7,7 @@ public static class FileContextDefaults
     public const long MaximumGeneratedFileBytes = 64L * 1024L * 1024L;
     public const int FirstLineNumber = 1;
     public const int MaximumPdfReadBytes = 100 * 1024 * 1024;
+    public const int MaximumConcurrentPdfOperations = 1;
     public const int MaximumImageBytes = 8 * 1024 * 1024;
     public const int MaximumRenderedPagePixels = 4_000_000;
     public const int MaximumImagesPerPdfPage = 20;

src/ManagedCode.FileContext/FileContextOptions.cs

@@ -23,6 +23,9 @@ public sealed class FileContextOptions
 
     public int MaximumPdfReadBytes { get; set; } = FileContextDefaults.MaximumPdfReadBytes;
 
+    /// <summary>Maximum simultaneous PDF reads/renders per shared processor, including source buffering.</summary>
+    public int MaximumConcurrentPdfOperations { get; set; } = FileContextDefaults.MaximumConcurrentPdfOperations;
+
     public int MaximumImageBytes { get; set; } = FileContextDefaults.MaximumImageBytes;
 
     public int MaximumRenderedPagePixels { get; set; } = FileContextDefaults.MaximumRenderedPagePixels;
@@ -75,6 +78,7 @@ internal void Validate()
     {
         ValidatePositive(MaximumGeneratedFileBytes, nameof(MaximumGeneratedFileBytes));
         ValidatePositive(MaximumPdfReadBytes, nameof(MaximumPdfReadBytes));
+        ValidatePositive(MaximumConcurrentPdfOperations, nameof(MaximumConcurrentPdfOperations));
         ValidatePositive(MaximumImageBytes, nameof(MaximumImageBytes));
         ValidatePositive(MaximumRenderedPagePixels, nameof(MaximumRenderedPagePixels));
         ValidatePositive(MaximumImagesPerPdfPage, nameof(MaximumImagesPerPdfPage));

src/ManagedCode.FileContext/FileContextService.Pdf.cs

@@ -17,27 +17,37 @@ public Task<FileContextPdfText> ReadPdfTextAsync(string path,
             throw new ArgumentOutOfRangeException(nameof(maxCharacters));
         }
         return FileContextOperation.RunAsync(_options.OperationTimeout, async token =>
-            FileContextPdfTextExtractor.Extract(await ReadPdfBytesAsync(path, token).ConfigureAwait(false), maxCharacters), cancellationToken);
+        {
+            using var permit = await _pdfProcessor.AcquireAsync(token).ConfigureAwait(false);
+            return FileContextPdfTextExtractor.Extract(await ReadPdfBytesAsync(path, token).ConfigureAwait(false), maxCharacters);
+        }, cancellationToken);
     }
 
     public Task<DataContent> RenderPdfPageAsync(string path, int pageNumber,
         CancellationToken cancellationToken = default) =>
         FileContextOperation.RunAsync(_options.OperationTimeout, async token =>
-            FileContextImageContent.FromPngBytes(FileContextPdfImages.RenderPagePng(
-                await ReadPdfBytesAsync(path, token).ConfigureAwait(false), pageNumber, _options), _options), cancellationToken);
+        {
+            using var permit = await _pdfProcessor.AcquireAsync(token).ConfigureAwait(false);
+            return FileContextImageContent.FromPngBytes(FileContextPdfImages.RenderPagePng(
+                await ReadPdfBytesAsync(path, token).ConfigureAwait(false), pageNumber, _options), _options);
+        }, cancellationToken);
 
     public Task<int> CountPdfPageImagesAsync(string path, int pageNumber,
         CancellationToken cancellationToken = default) =>
         FileContextOperation.RunAsync(_options.OperationTimeout, async token =>
-            FileContextPdfImages.ExtractPageImagesPng(
-                await ReadPdfBytesAsync(path, token).ConfigureAwait(false), pageNumber, _options).Count, cancellationToken);
+        {
+            using var permit = await _pdfProcessor.AcquireAsync(token).ConfigureAwait(false);
+            return FileContextPdfImages.ExtractPageImagesPng(
+                await ReadPdfBytesAsync(path, token).ConfigureAwait(false), pageNumber, _options).Count;
+        }, cancellationToken);
 
     public Task<DataContent> ExtractPdfImageAsync(string path, int pageNumber, int imageNumber,
         CancellationToken cancellationToken = default)
     {
         ArgumentOutOfRangeException.ThrowIfLessThan(imageNumber, 1);
         return FileContextOperation.RunAsync(_options.OperationTimeout, async token =>
         {
+            using var permit = await _pdfProcessor.AcquireAsync(token).ConfigureAwait(false);
             var images = FileContextPdfImages.ExtractPageImagesPng(
                 await ReadPdfBytesAsync(path, token).ConfigureAwait(false), pageNumber, _options);
             if (imageNumber > images.Count)

src/ManagedCode.FileContext/FileContextService.cs

@@ -9,13 +9,16 @@ public sealed partial class FileContextService : IFileContext, IFileContextPdf
 {
     private readonly ManagedCodeStorageFileStore _fileStore;
     private readonly FileContextOptions _options;
+    private readonly Pdf.FileContextPdfProcessor _pdfProcessor;
 
     /// <summary>Creates the extended file-context service.</summary>
-    public FileContextService(ManagedCodeStorageFileStore fileStore, FileContextOptions? options = null)
+    public FileContextService(ManagedCodeStorageFileStore fileStore, FileContextOptions? options = null,
+        Pdf.FileContextPdfProcessor? pdfProcessor = null)
     {
         _fileStore = fileStore ?? throw new ArgumentNullException(nameof(fileStore));
         _options = options ?? new FileContextOptions();
         _options.Validate();
+        _pdfProcessor = pdfProcessor ?? Pdf.FileContextPdfProcessor.Shared;
         Documents = new FileContextDocumentService(_fileStore, _options);
     }
 

src/ManagedCode.FileContext/FileContextServiceCollectionExtensions.cs

@@ -1,3 +1,4 @@
+using ManagedCode.FileContext.Pdf;
 using ManagedCode.Storage.Core;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.Configuration;
@@ -21,6 +22,7 @@ public static IServiceCollection AddManagedCodeFileContext(
             builder.Configure(configure);
         }
         AddOptionsValidator(services);
+        AddPdfProcessor(services);
 
         services.TryAddSingleton(static provider => provider.GetRequiredService<IOptions<FileContextOptions>>().Value);
         services.TryAddSingleton<ManagedCodeStorageFileStore>();
@@ -58,14 +60,16 @@ public static IServiceCollection AddKeyedManagedCodeFileContext(
         }
         AddOptionsValidator(services);
 
+        AddPdfProcessor(services);
         services.AddKeyedSingleton<FileContextOptions>(serviceKey, (provider, _) =>
             provider.GetRequiredService<IOptionsMonitor<FileContextOptions>>().Get(optionsName));
         services.AddKeyedSingleton<ManagedCodeStorageFileStore>(serviceKey, (provider, key) =>
             new ManagedCodeStorageFileStore(provider.GetRequiredKeyedService<IStorage>(key),
                 provider.GetRequiredKeyedService<FileContextOptions>(key)));
         services.AddKeyedSingleton<IFileContext>(serviceKey, (provider, key) =>
             new FileContextService(provider.GetRequiredKeyedService<ManagedCodeStorageFileStore>(key),
-                provider.GetRequiredKeyedService<FileContextOptions>(key)));
+                provider.GetRequiredKeyedService<FileContextOptions>(key),
+                provider.GetRequiredService<FileContextPdfProcessor>()));
         services.AddKeyedSingleton<IFileContextPdf>(serviceKey, (provider, key) =>
             (IFileContextPdf)provider.GetRequiredKeyedService<IFileContext>(key));
         services.AddKeyedSingleton<FileContextProvider>(serviceKey, (provider, key) =>
@@ -88,9 +92,14 @@ public static IServiceCollection AddFileContextOptions(this IServiceCollection s
         services.AddOptions<FileContextOptions>()
             .Bind(configuration.GetSection(FileContextOptions.SectionName));
         AddOptionsValidator(services);
+        AddPdfProcessor(services);
         return services;
     }
 
+    private static void AddPdfProcessor(IServiceCollection services) =>
+        services.TryAddSingleton(static provider => new FileContextPdfProcessor(
+            provider.GetRequiredService<IOptions<FileContextOptions>>().Value));
+
     private static void AddOptionsValidator(IServiceCollection services) =>
         services.TryAddEnumerable(ServiceDescriptor.Singleton<IValidateOptions<FileContextOptions>, FileContextOptionsValidator>());
 }

src/ManagedCode.FileContext/Pdf/FileContextPdfImages.cs

@@ -24,29 +24,8 @@ public static byte[] RenderPagePng(byte[] pdf, int pageNumber, FileContextOption
         double? scale = null)
     {
         ArgumentNullException.ThrowIfNull(options);
-        var settings = ValidateInput(pdf, options);
-        var resolvedScale = scale ?? settings.DefaultPdfPageScale;
-        if (resolvedScale < settings.MinimumPdfPageScale || resolvedScale > settings.MaximumPdfPageScale
-            || !double.IsFinite(resolvedScale))
-        {
-            throw new ArgumentOutOfRangeException(nameof(scale));
-        }
-
-        using var document = PdfDocument.Open(pdf, SkiaRenderingParsingOptions.Instance);
-        ValidatePage(pageNumber, document.NumberOfPages);
-        var page = document.GetPage(pageNumber);
-        if (page.Width * resolvedScale * page.Height * resolvedScale > settings.MaximumRenderedPagePixels)
-        {
-            throw new IOException("The rendered PDF page exceeds the pixel limit.");
-        }
-
-        document.AddSkiaPageFactory();
-        using var image = document.GetPageAsPng(pageNumber, (float)resolvedScale, settings.PdfPngQuality);
-        if (image.Length > settings.MaximumImageBytes)
-        {
-            throw new IOException("The rendered PDF page exceeds the image byte limit.");
-        }
-        return image.ToArray();
+        using var document = new FileContextPdfRenderDocument(pdf, options);
+        return document.RenderPagePng(pageNumber, scale);
     }
 
     /// <summary>Extracts the embedded images on one page; these do not include page text or vector drawings.</summary>

src/ManagedCode.FileContext/Pdf/FileContextPdfProcessor.cs

@@ -0,0 +1,41 @@
+namespace ManagedCode.FileContext.Pdf;
+
+/// <summary>Bounds concurrent PDF source reads and processing across scoped file contexts.</summary>
+public sealed class FileContextPdfProcessor : IDisposable
+{
+    /// <summary>Shared default processor for manually composed file contexts.</summary>
+    public static FileContextPdfProcessor Shared { get; } = new(new FileContextOptions());
+
+    private readonly SemaphoreSlim _permits;
+
+    public FileContextPdfProcessor(FileContextOptions options)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+        options.Validate();
+        _permits = new SemaphoreSlim(options.MaximumConcurrentPdfOperations, options.MaximumConcurrentPdfOperations);
+    }
+
+    /// <summary>Waits before downloading or buffering a PDF. Dispose the permit after processing completes.</summary>
+    public async Task<IDisposable> AcquireAsync(CancellationToken cancellationToken = default)
+    {
+        await _permits.WaitAsync(cancellationToken).ConfigureAwait(false);
+        return new Permit(_permits);
+    }
+
+    public void Dispose() => _permits.Dispose();
+
+    private sealed class Permit(SemaphoreSlim permits) : IDisposable
+    {
+        private bool _disposed;
+
+        public void Dispose()
+        {
+            if (_disposed)
+            {
+                return;
+            }
+            _disposed = true;
+            permits.Release();
+        }
+    }
+}