using System.Globalization;
using System.Text.Json;
using Febe.Core.Domain;
namespace Febe.Core.Collection.Readers;
///
/// The generic reader (spec §6.4): walks any JSON tree and recognizes, wherever they are, the nodes that look like a
/// content (identifier, date, image or video versions, possibly a series), a profile (identifier and user name), a
/// highlight collection (identifier and title) and the pagination of a page. Which keys mean what comes from the
/// site's , never from fixed paths or addresses.
///
///
/// Version choice (spec §6.5 point 1): the largest image; for videos the largest among the versions complete with
/// audio (versions that do not say are taken as complete), or the largest of all when none has audio.
/// Thread-safe: the reader keeps no state between calls.
///
public sealed class ShapeReader
{
private const int MaxDepth = 64;
private readonly ReaderVocabulary _v;
private readonly HashSet _relevance;
public ShapeReader(ReaderVocabulary vocabulary)
{
_v = vocabulary ?? throw new ArgumentNullException(nameof(vocabulary));
_relevance = new HashSet(vocabulary.Relevance, StringComparer.Ordinal);
}
public ReaderVocabulary Vocabulary => _v;
/// Reads one response body. Never throws on unexpected shapes: they become .
public ReadResult Read(JsonElement root)
{
var walk = new Walk();
Visit(root, walk, owner: null, highlightId: null, depth: 0);
if (walk.ViewerId is { } viewerId && walk.Profiles.TryGetValue(viewerId, out var own))
{
// The connected account described by its identifier only, and its profile elsewhere in the same answer.
walk.Profiles[viewerId] = own with { IsViewer = true };
}
var profiles = walk.Profiles.Values.ToList();
var viewer = profiles.FirstOrDefault(p => p.IsViewer);
if (walk.Contents.Count > 0 || walk.Highlights.Count > 0 || profiles.Count > 0)
{
return new ReadResult
{
Shape = ReadShape.Recognized,
Contents = walk.Contents,
Profiles = profiles,
Highlights = walk.Highlights,
Page = walk.Page,
Viewer = viewer,
ViewerId = viewer?.Id ?? walk.ViewerId,
};
}
if (IsEmptyShape(root, walk.Page is not null))
{
return new ReadResult { Shape = ReadShape.Empty, Page = walk.Page, ViewerId = walk.ViewerId };
}
if (_relevance.Count > 0 && !HasAnyKey(root, 0))
{
return new ReadResult { Shape = ReadShape.Unrelated, ViewerId = walk.ViewerId };
}
return new ReadResult { Shape = ReadShape.Unrecognized, Page = walk.Page, KeyStructure = KeyStructure.Describe(root) };
}
/// Reads a body given as text (tests, probe samples).
public ReadResult Read(string json)
{
using var document = JsonDocument.Parse(json, new JsonDocumentOptions { MaxDepth = 256 });
return Read(document.RootElement);
}
private void Visit(JsonElement node, Walk walk, ProfileInfo? owner, string? highlightId, int depth)
{
if (depth > MaxDepth)
{
return;
}
if (node.ValueKind == JsonValueKind.Array)
{
foreach (var item in node.EnumerateArray())
{
Visit(item, walk, owner, highlightId, depth + 1);
}
return;
}
if (node.ValueKind != JsonValueKind.Object)
{
return;
}
if (walk.Page is null && (_v.Page.HasMore.Has(node) || _v.Page.Cursor.Has(node)))
{
walk.Page = new PageInfo(
_v.Page.HasMore.TryGet(node, out var more) ? AsBool(more) : null,
_v.Page.Cursor.TryGet(node, out var cursor) ? AsText(cursor) : null);
}
if (_v.Viewer.TryGet(node, out var viewerNode))
{
if (ReadProfile(viewerNode) is { } viewer)
{
walk.AddProfile(viewer with { IsViewer = true });
}
else if (viewerNode.ValueKind == JsonValueKind.Object)
{
// Instagram describes the connected account with its identifier only (xdt_viewer.user): kept, so a
// profile with the same identifier can be recognized as the connected account (H10).
walk.ViewerId ??= AsText(Get(_v.Profile.Id, viewerNode));
}
}
if (IsContent(node))
{
if (ReadContent(node, walk, owner, highlightId) is { } item)
{
walk.Contents.Add(item);
}
return;
}
if (IsHighlight(node))
{
var highlightOwner = _v.Highlight.Owner.TryGet(node, out var ho) ? ReadProfile(ho) ?? owner : owner;
if (highlightOwner is not null)
{
walk.AddProfile(highlightOwner);
}
var id = HighlightId(AsText(Get(_v.Highlight.Id, node))!);
var before = walk.Contents.Count;
if (_v.Highlight.Items.TryGet(node, out var items))
{
Visit(items, walk, highlightOwner, id, depth + 1);
}
walk.Highlights.Add(new HighlightInfo
{
Id = id,
Title = AsText(Get(_v.Highlight.Title, node)) ?? string.Empty,
Owner = highlightOwner,
Cover = _v.Highlight.Cover.TryGet(node, out var cover) ? ReadVersion(cover) : null,
Items = walk.Contents.Skip(before).ToList(),
Order = walk.Highlights.Count,
});
return;
}
var inherited = owner;
if (ReadProfile(node) is { } profile)
{
walk.AddProfile(profile);
inherited = profile;
}
else if (_v.Content.Owner.TryGet(node, out var ownerNode) && ReadProfile(ownerNode) is { } declared)
{
// An object that declares an author for what it contains (e.g. the stories of one account).
walk.AddProfile(declared);
inherited = declared;
}
foreach (var property in node.EnumerateObject())
{
if (property.Value.ValueKind is JsonValueKind.Object or JsonValueKind.Array)
{
Visit(property.Value, walk, inherited, highlightId, depth + 1);
}
}
}
private bool IsContent(JsonElement node) =>
_v.Content.Id.Has(node) && _v.Content.TakenAt.Has(node)
&& (_v.Content.Images.Has(node) || _v.Content.Videos.Has(node) || _v.Content.Children.Has(node));
///
/// A highlight collection: identifier and title, and — when the vocabulary names them — an owner or its items, so
/// that any other object with an «id» and a «title» (a promotion, a section of a page) is not taken for one.
///
private bool IsHighlight(JsonElement node) =>
_v.Highlight.Id.Has(node) && _v.Highlight.Title.Has(node) && AsText(Get(_v.Highlight.Id, node)) is not null
&& ((!_v.Highlight.Owner.IsSet && !_v.Highlight.Items.IsSet) || _v.Highlight.Owner.Has(node) || _v.Highlight.Items.Has(node));
///
/// The identifier of a collection as its address carries it: Instagram writes «highlight:17841…» in the data and
/// «/stories/highlights/17841…/» in the address (HAR of 21/10/2026), so a «kind:» prefix made of letters is dropped.
///
internal static string HighlightId(string id)
{
var colon = id.IndexOf(':', StringComparison.Ordinal);
return colon > 0 && colon < id.Length - 1 && id.AsSpan(0, colon).IndexOfAnyExcept(Letters) < 0 ? id[(colon + 1)..] : id;
}
private static readonly System.Buffers.SearchValues Letters =
System.Buffers.SearchValues.Create("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_");
private ContentItem? ReadContent(JsonElement node, Walk walk, ProfileInfo? inheritedOwner, string? highlightId)
{
var id = AsText(Get(_v.Content.Id, node));
var takenAt = AsTime(Get(_v.Content.TakenAt, node));
if (id is null || takenAt is null)
{
return null;
}
var owner = _v.Content.Owner.TryGet(node, out var ownerNode) ? ReadProfile(ownerNode) ?? inheritedOwner : inheritedOwner;
if (owner is not null)
{
walk.AddProfile(owner);
}
var files = new List();
var hasChildren = _v.Content.Children.TryGet(node, out var children) && children.ValueKind == JsonValueKind.Array && children.GetArrayLength() > 0;
var declaredChildren = 0;
if (hasChildren)
{
foreach (var child in children.EnumerateArray())
{
declaredChildren++;
if (child.ValueKind == JsonValueKind.Object && ReadFile(child) is { } file)
{
files.Add(file with { Position = declaredChildren });
}
}
}
else if (ReadFile(node) is { } single)
{
files.Add(single);
}
var complete = files.Count > 0 && (!hasChildren || files.Count == declaredChildren);
if (_v.Content.ChildCount.TryGet(node, out var countNode) && AsInt(countNode) is { } declared && declared > files.Count)
{
complete = false;
}
return new ContentItem
{
Id = id,
Code = AsText(Get(_v.Content.Code, node)),
TakenAt = takenAt.Value,
Caption = AsText(Get(_v.Content.Caption, node)),
Owner = owner,
Pinned = _v.Content.Pinned.TryGet(node, out var pinned) && AsBool(pinned) == true,
ExpiresAt = AsTime(Get(_v.Content.ExpiresAt, node)),
Files = files,
IsComplete = complete,
HighlightId = highlightId,
Order = walk.Contents.Count,
};
}
private ContentFile? ReadFile(JsonElement node)
{
var videos = _v.Content.Videos.TryGet(node, out var v) ? ReadVersions(v) : [];
var images = _v.Content.Images.TryGet(node, out var i) ? ReadVersions(i) : [];
var id = AsText(Get(_v.Content.Id, node));
var largestImage = images.Count == 0 ? null : images.MaxBy(x => x.Version.Area);
if (videos.Count > 0)
{
var complete = videos.Where(x => x.Version.HasAudio != false).ToList();
var best = (complete.Count > 0 ? complete : videos).MaxBy(x => x.Version.Area)!;
var duration = AsSeconds(Get(_v.Content.Duration, node)) ?? AsSeconds(Get(_v.Content.Duration, best.Node));
return new ContentFile(MediaKind.Video, id, best.Version, largestImage?.Version, duration);
}
return largestImage is null ? null : new ContentFile(MediaKind.Photo, id, largestImage.Version, null, null);
}
private List ReadVersions(JsonElement value)
{
var list = new List();
switch (value.ValueKind)
{
case JsonValueKind.Array:
foreach (var item in value.EnumerateArray())
{
if (ReadVersion(item) is { } version)
{
list.Add(new VersionNode(version, item));
}
}
break;
case JsonValueKind.Object:
case JsonValueKind.String:
if (ReadVersion(value) is { } single)
{
list.Add(new VersionNode(single, value));
}
break;
}
return list;
}
private FileVersion? ReadVersion(JsonElement node)
{
if (node.ValueKind == JsonValueKind.String)
{
return IsAddress(node.GetString()) ? new FileVersion(node.GetString()!, null, null, null) : null;
}
if (node.ValueKind != JsonValueKind.Object)
{
return null;
}
var url = AsText(Get(_v.Version.Url, node));
if (!IsAddress(url))
{
return null;
}
return new FileVersion(
url!,
AsInt(Get(_v.Version.Width, node)),
AsInt(Get(_v.Version.Height, node)),
_v.Version.HasAudio.TryGet(node, out var audio) ? AsBool(audio) : null);
}
private ProfileInfo? ReadProfile(JsonElement node)
{
if (node.ValueKind != JsonValueKind.Object)
{
return null;
}
var id = AsText(Get(_v.Profile.Id, node));
var username = AsText(Get(_v.Profile.Username, node));
if (id is null || string.IsNullOrWhiteSpace(username))
{
return null;
}
FileVersion? picture = null;
if (_v.Profile.Picture.TryGet(node, out var pictureNode))
{
picture = ReadVersions(pictureNode).MaxBy(x => x.Version.Area)?.Version;
}
return new ProfileInfo
{
Id = id,
Username = username.Trim(),
DisplayName = AsText(Get(_v.Profile.DisplayName, node)),
IsPrivate = _v.Profile.IsPrivate.TryGet(node, out var p) ? AsBool(p) : null,
IsFollowed = _v.Profile.IsFollowed.TryGet(node, out var f) ? AsBool(f) : null,
PostCount = AsInt(Get(_v.Profile.PostCount, node)),
Picture = picture,
LatestStoryAt = AsTime(Get(_v.Profile.LatestStoryAt, node)),
};
}
/// True when one of the relevance keys of the vocabulary is a property name anywhere under .
private bool HasAnyKey(JsonElement element, int depth)
{
if (depth > MaxDepth)
{
return false;
}
switch (element.ValueKind)
{
case JsonValueKind.Object:
foreach (var property in element.EnumerateObject())
{
if (_relevance.Contains(property.Name) || HasAnyKey(property.Value, depth + 1))
{
return true;
}
}
return false;
case JsonValueKind.Array:
foreach (var item in element.EnumerateArray())
{
if (HasAnyKey(item, depth + 1))
{
return true;
}
}
return false;
default:
return false;
}
}
///
/// «Empty»: no list with elements anywhere, and either a recognized pagination or only plain values at the top
/// (a bare status or error). Anything richer that nothing recognized is an unknown shape.
///
private static bool IsEmptyShape(JsonElement root, bool hasPage)
{
var nested = false;
var nonEmptyArray = false;
Scan(root, 0, ref nested, ref nonEmptyArray);
return !nonEmptyArray && (hasPage || !nested);
}
private static void Scan(JsonElement element, int depth, ref bool nested, ref bool nonEmptyArray)
{
if (depth > MaxDepth)
{
return;
}
switch (element.ValueKind)
{
case JsonValueKind.Object:
foreach (var property in element.EnumerateObject())
{
if (property.Value.ValueKind == JsonValueKind.Object)
{
nested = true;
}
Scan(property.Value, depth + 1, ref nested, ref nonEmptyArray);
}
break;
case JsonValueKind.Array:
if (element.GetArrayLength() > 0)
{
nonEmptyArray = true;
}
break;
}
}
private static JsonElement Get(VocabularyKeys keys, JsonElement node) => keys.TryGet(node, out var value) ? value : default;
private static bool IsAddress(string? text) =>
!string.IsNullOrWhiteSpace(text)
&& Uri.TryCreate(text, UriKind.Absolute, out var uri)
&& uri.Scheme is "http" or "https";
internal static string? AsText(JsonElement value) => value.ValueKind switch
{
JsonValueKind.String => string.IsNullOrEmpty(value.GetString()) ? null : value.GetString(),
JsonValueKind.Number => value.GetRawText(),
_ => null,
};
internal static int? AsInt(JsonElement value)
{
switch (value.ValueKind)
{
case JsonValueKind.Number when value.TryGetInt32(out var i):
return i;
case JsonValueKind.Number when value.TryGetDouble(out var d) && d is >= int.MinValue and <= int.MaxValue:
return (int)Math.Round(d);
case JsonValueKind.String when int.TryParse(value.GetString(), NumberStyles.Integer, CultureInfo.InvariantCulture, out var s):
return s;
default:
return null;
}
}
internal static bool? AsBool(JsonElement value) => value.ValueKind switch
{
JsonValueKind.True => true,
JsonValueKind.False => false,
JsonValueKind.Number => value.TryGetInt64(out var n) ? n != 0 : null,
JsonValueKind.String => value.GetString()?.Trim().ToLowerInvariant() switch
{
"true" or "1" or "sì" or "si" => true,
"false" or "0" or "no" => false,
_ => null,
},
_ => null,
};
internal static TimeSpan? AsSeconds(JsonElement value)
{
double? seconds = value.ValueKind switch
{
JsonValueKind.Number when value.TryGetDouble(out var d) => d,
JsonValueKind.String when double.TryParse(value.GetString(), NumberStyles.Float, CultureInfo.InvariantCulture, out var s) => s,
_ => null,
};
return seconds is { } x && x >= 0 && x < 1e7 ? TimeSpan.FromSeconds(x) : null;
}
/// A date: Unix seconds (milliseconds when larger than 10^11), or ISO 8601 text.
internal static DateTimeOffset? AsTime(JsonElement value)
{
switch (value.ValueKind)
{
case JsonValueKind.Number when value.TryGetDouble(out var n):
return FromUnix(n);
case JsonValueKind.String:
var text = value.GetString();
if (double.TryParse(text, NumberStyles.Float, CultureInfo.InvariantCulture, out var numeric))
{
return FromUnix(numeric);
}
return DateTimeOffset.TryParse(text, CultureInfo.InvariantCulture, DateTimeStyles.AssumeUniversal | DateTimeStyles.AdjustToUniversal, out var parsed)
? parsed
: null;
default:
return null;
}
}
private static DateTimeOffset? FromUnix(double value)
{
if (value <= 0 || double.IsNaN(value))
{
return null;
}
var ms = value > 1e11 ? value : value * 1000;
return ms < 253402300799000 ? DateTimeOffset.FromUnixTimeMilliseconds((long)ms) : null;
}
private sealed record VersionNode(FileVersion Version, JsonElement Node);
private sealed class Walk
{
public List Contents { get; } = [];
public List Highlights { get; } = [];
public Dictionary Profiles { get; } = new(StringComparer.Ordinal);
public PageInfo? Page { get; set; }
/// Identifier of the connected account when the answer gives no more than that.
public string? ViewerId { get; set; }
/// Merges what different parts of a response say about the same profile.
public void AddProfile(ProfileInfo profile)
{
if (!Profiles.TryGetValue(profile.Id, out var known))
{
Profiles[profile.Id] = profile;
return;
}
Profiles[profile.Id] = known with
{
DisplayName = known.DisplayName ?? profile.DisplayName,
IsPrivate = known.IsPrivate ?? profile.IsPrivate,
IsFollowed = known.IsFollowed ?? profile.IsFollowed,
PostCount = known.PostCount ?? profile.PostCount,
Picture = known.Picture ?? profile.Picture,
LatestStoryAt = known.LatestStoryAt ?? profile.LatestStoryAt,
IsViewer = known.IsViewer || profile.IsViewer,
};
}
}
}