PowerForge.Web.Protocols 3.0.171

PowerForge.Web.Protocols

Read and write web interchange documents without loading a website generator or browser engine. The package supports .NET 8 and .NET Framework 4.7.2 and has no external runtime package dependencies. It uses the platform XML and JSON serializers; Framework uses its built-in System.Web.Extensions serializer.

The library contains:

• IndexNow submission, batching, bounded retries, cancellation, and response diagnostics.
• Sitemap URL-set and index readers, XML creation, count/UTF-8-size partitioning, and bundled offline schemas.
• RSS and Atom readers and writers, and a JSON Feed 1.1 writer.
• Safe JSON-LD serialization for publisher-supplied dictionaries and graphs.

Ownership

Readers do not fetch linked resources. XML readers prohibit DTDs and external entity resolution and bound document characters to 64 MiB. Caller acquisition limits should also bound downloaded bytes. Feed content remains untrusted markup; callers decide how to render or sanitize it. Sitemap modification dates remain distinct from article publication dates.

Read a feed or sitemap

using PowerForge.Web.Protocols.Feeds;
using PowerForge.Web.Protocols.Sitemaps;

var feed = SyndicationReader.ParseSyndicationFeed(xml, new Uri(feedUrl), feedUrl);
foreach (var item in feed.Items)
    Console.WriteLine($"{item.Id}: {item.Title} ({item.Published})");

var sitemap = SitemapReader.Read(sitemapXml, new Uri(sitemapUrl));
// The application decides whether to traverse an index and which pages to fetch.

Feed models normalize supported metadata, including identifiers, separate publication/update dates, authors, categories, and content. Unknown foreign-namespace extension elements are retained. This is not a lossless XML editor: original prefixes, whitespace, and every optional format construct are not preserved. RSS 1.0 uses its declared RDF sequence when present, otherwise document order. RSS IDs marked isPermaLink="false" are not used as fallback article URLs. Feed and item source URLs use the caller-supplied source first, then a resolved Atom self link when available.

Write publisher-selected entries

var output = SyndicationWriter.WriteRss(new SyndicationFeed
{
    Title = "News",
    Url = "https://example.org/news/",
    SourceFeedUrl = "https://example.org/news/rss.xml",
    Description = "Published updates",
    Items = new[]
    {
        new SyndicationItem
        {
            Id = "update-42",
            Url = "https://example.org/news/update-42/",
            Title = "A published update",
            Summary = "The publisher's summary.",
            Published = publishedAt
        }
    }
});

Atom writers require absolute feed/entry IRIs, update dates, and a feed author or authors on every entry. JSON Feed requires entry IDs and supplies content_text from the summary when a full body is absent. The library does not invent publication dates, authors, site identities, or ordering.

Inline Atom XML media content retains its element structure and namespaces. XML and XHTML bodies are parsed with the same DTD prohibition and size bounds as feed input; text, escaped HTML and binary Base64 bodies remain text. Out-of-line Atom content references are exposed as ContentSourceUrl, resolved against XML bases, and preserved by Atom writing without fetching the target.

JSON Feed marks known HTML/XHTML content as content_html. Other explicit media types are preserved as literal content_text, including serialized XML and Base64; the writer does not decode binary bodies. An unspecified content type retains the HTML default.

SitemapWriter.Create writes a nonempty URL set or index and URL-escapes locations, validates their final length, and validates XML date values. The stream reader honors XML encoding declarations and leaves the input stream open. Partition accepts URL XML elements, preserving extension elements, and returns documents bounded by the 50,000-entry and 50 MiB limits. Empty partitions return no documents. File names, index URLs, ownership markers, and obsolete-file removal remain caller decisions. The bundled sitemaps.org schemas validate the base protocol; extensions require their own validation.

Embed structured data

using PowerForge.Web.Protocols.StructuredData;

var script = JsonLdWriter.WriteScript(new Dictionary<string, object?>
{
    ["@context"] = "https://schema.org",
    ["@type"] = "Article",
    ["headline"] = title,
    ["datePublished"] = publishedAt.ToString("O")
});

Use JSON-compatible dictionaries, arrays, strings, numbers, booleans and null. Supply dates as ISO strings. Script-sensitive characters are escaped. This API does not load remote contexts, expand or compact JSON-LD, reason about RDF, choose Schema.org entities, or promise search-engine eligibility.

IndexNow

Reference PowerForge.Web.Protocols and import PowerForge.Web.Protocols.IndexNow. Existing consumers of the retired PowerForge.IndexNow package must update their package reference and namespace, then rebuild. Transport uses an optional caller-owned HttpClient; durable queues, checkpoints and operational retry scheduling belong to the application.

RetryCount limits additional attempts for HTTP 408, 429, server errors (5xx), and transport failures. Permanent refusals such as 400, 403, and 422 return immediately. RetryDelayMs sets the initial delay; subsequent delays double up to 60 seconds. A valid Retry-After duration or HTTP date sets a minimum wait even when RetryDelayMs is zero. If that wait exceeds 60 seconds or the attempt limit is reached, the batch fails with its outstanding server deadline in IndexNowRequestResult.RetryNotBefore. Remaining batches and hosts for the same endpoint are reported as failed, deferred results with zero attempts and the same deadline; other endpoints can continue. Caller cancellation interrupts requests and retry waits.

RetryNotBefore is an absolute timestamp for caller-managed rescheduling. The transport enforces it during the current submission operation; it does not keep throttle state between separate calls or processes. Applications that retry across operations must retain and enforce reported deadlines. The web pipeline includes deadlines in its JSON report and summaries and retains the existing sitemap checkpoint when a batch fails or is deferred; the checkpoint records successful sitemap coverage, not throttle state.

A received 2xx status acknowledges delivery. Failure or an internal timeout while reading the optional response preview adds a warning and does not resend the accepted batch or prevent successful checkpoint coverage. Caller cancellation still stops the operation and later sends. A transport failure before a status arrives has an unknown delivery outcome and may be retried; this transport does not promise exactly-once delivery.