"""Cross-protocol translation engine for Fleetmesh.
Provides bidirectional translation across the four supported social protocols:
- Nostr (NIP-01 Kind 1 / e-tag threading)
- AT Protocol (app.bsky.feed.post)
- ActivityPub (ActivityStreams 2.0 Create / Note)
- Secure Scuttlebutt (post)
Uses UnifiedPost as the canonical intermediate representation for maximum fidelity.
"""
from __future__ import annotations
from dataclasses import dataclass, field
import datetime
import html
import re
import time
from typing import Any, Mapping, MutableMapping, Optional
[docs]@dataclass
class UnifiedPost:
"""Canonical intermediate representation of a social microblog post."""
text: str
author: str = ""
created_at: int = 0
attachments: list[str] = field(default_factory=list)
reply_to: Optional[str] = None
root: Optional[str] = None
tags: list[str] = field(default_factory=list)
extra: Mapping[str, Any] = field(default_factory=dict)
[docs]def unix_to_iso(ts: int) -> str:
"""Format unix seconds to ISO 8601 UTC string."""
dt = datetime.datetime.fromtimestamp(ts, tz=datetime.timezone.utc)
return dt.strftime('%Y-%m-%dT%H:%M:%S.000Z')
[docs]def iso_to_unix(iso_str: str) -> int:
"""Parse ISO 8601 string to unix seconds."""
clean = iso_str.strip()
if clean.endswith('Z'):
clean = clean[:-1] + '+00:00'
try:
dt = datetime.datetime.fromisoformat(clean)
return int(dt.timestamp())
except Exception:
return int(time.time())
[docs]def strip_html(text: str) -> str:
"""Strip HTML tags, scripts, and unescape HTML entities for clean text representation."""
# First completely remove <script> and <style> blocks
s = re.sub(r'<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>', '', text, flags=re.IGNORECASE)
s = re.sub(r'<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>', '', s, flags=re.IGNORECASE)
# Replace <br> and <p> with newlines
s = re.sub(r'<br\s*/?>', '\n', s, flags=re.IGNORECASE)
s = re.sub(r'</p>', '\n', s, flags=re.IGNORECASE)
s = re.sub(r'<[^>]+>', '', s)
s = html.unescape(s)
return s.strip()
[docs]def text_to_html(text: str) -> str:
"""Convert plain text to safe HTML paragraphs and line breaks."""
escaped = html.escape(text)
paragraphs = escaped.split('\n\n')
formatted = []
for p in paragraphs:
lines = p.split('\n')
formatted.append(f"<p>{'<br/>'.join(lines)}</p>")
return ''.join(formatted)
# -----------------------------------------------------------------------------
# Nostr (NIP-01 / e-tag threading) Translation
# -----------------------------------------------------------------------------
[docs]def nostr_to_unified(event: Mapping[str, Any]) -> UnifiedPost:
"""Translate a Nostr Kind 1 event to UnifiedPost."""
text = str(event.get('content', ''))
author = str(event.get('pubkey', ''))
created_at = int(event.get('created_at', 0)) or int(time.time())
tags = event.get('tags', [])
reply_to = None
root = None
hashtags: list[str] = []
attachments: list[str] = []
# Parse e-tag reply/root markers
e_tags = [t for t in tags if len(t) >= 2 and t[0] == 'e']
for t in e_tags:
eid = t[1]
marker = t[3] if len(t) >= 4 else None
if marker == 'reply':
reply_to = eid
elif marker == 'root':
root = eid
elif marker is None:
# Positional fallback (deprecated positional conventions)
if not root:
root = eid
else:
reply_to = eid
if reply_to is None and root is not None:
reply_to = root
for t in tags:
if len(t) >= 2:
if t[0] == 't':
hashtags.append(t[1].lower())
elif t[0] in ('r', 'image', 'imeta'):
if t[0] == 'imeta':
for part in t[1:]:
if part.startswith('url '):
attachments.append(part[4:])
else:
attachments.append(t[1])
# Extract image URLs from content if not explicitly tagged
url_matches = re.findall(r'https?://\S+\.(?:png|jpg|jpeg|gif|webp)', text, re.IGNORECASE)
for u in url_matches:
if u not in attachments:
attachments.append(u)
return UnifiedPost(
text=text,
author=author,
created_at=created_at,
attachments=attachments,
reply_to=reply_to,
root=root,
tags=hashtags,
extra={"nostr_id": event.get("id")},
)
[docs]def unified_to_nostr(post: UnifiedPost, pubkey: Optional[str] = None) -> Mapping[str, Any]:
"""Translate UnifiedPost to a Nostr Kind 1 event structure."""
author = pubkey or post.author
tags: list[list[str]] = []
if post.root and post.reply_to and post.root != post.reply_to:
tags.append(["e", post.root, "", "root"])
tags.append(["e", post.reply_to, "", "reply"])
elif post.reply_to:
tags.append(["e", post.reply_to, "", "root"])
for tag in post.tags:
tags.append(["t", tag.lstrip('#')])
for att in post.attachments:
tags.append(["r", att])
return {
"kind": 1,
"pubkey": author,
"created_at": post.created_at or int(time.time()),
"tags": tags,
"content": post.text,
}
# -----------------------------------------------------------------------------
# AT Protocol (app.bsky.feed.post) Translation
# -----------------------------------------------------------------------------
[docs]def atproto_to_unified(record: Mapping[str, Any], author: str = "") -> UnifiedPost:
"""Translate an ATProto app.bsky.feed.post record to UnifiedPost."""
text = str(record.get('text', ''))
created_str = record.get('createdAt', '')
created_at = iso_to_unix(created_str) if created_str else int(time.time())
reply_info = record.get('reply', {})
reply_to = None
root = None
if isinstance(reply_info, dict):
parent_ref = reply_info.get('parent', {})
root_ref = reply_info.get('root', {})
if isinstance(parent_ref, dict):
reply_to = parent_ref.get('uri')
if isinstance(root_ref, dict):
root = root_ref.get('uri')
attachments: list[str] = []
embed = record.get('embed', {})
if isinstance(embed, dict):
images = embed.get('images', [])
for img in images:
if isinstance(img, dict):
blob = img.get('image', {})
if isinstance(blob, dict):
link = blob.get('ref', {}).get('$link') or blob.get('cid')
if link:
attachments.append(str(link))
# Tags from facets
tags: list[str] = []
facets = record.get('facets', [])
if isinstance(facets, list):
for facet in facets:
features = facet.get('features', [])
for feat in features:
if feat.get('$type') == 'app.bsky.richtext.facet#tag':
tag_name = feat.get('tag')
if tag_name:
tags.append(tag_name.lower())
return UnifiedPost(
text=text,
author=author,
created_at=created_at,
attachments=attachments,
reply_to=reply_to,
root=root,
tags=tags,
extra={"atproto_record": dict(record)},
)
[docs]def unified_to_atproto(post: UnifiedPost) -> Mapping[str, Any]:
"""Translate UnifiedPost to an ATProto app.bsky.feed.post record."""
record: MutableMapping[str, Any] = {
"$type": "app.bsky.feed.post",
"text": post.text,
"createdAt": unix_to_iso(post.created_at or int(time.time())),
}
if post.reply_to:
root_uri = post.root or post.reply_to
record["reply"] = {
"root": {"uri": root_uri, "cid": post.extra.get("root_cid", "")},
"parent": {"uri": post.reply_to, "cid": post.extra.get("reply_cid", "")},
}
if post.attachments:
images = []
for att in post.attachments:
images.append({
"alt": "",
"image": {
"$type": "blob",
"ref": {"$link": att},
"mimeType": "image/jpeg",
"size": 0,
},
})
record["embed"] = {
"$type": "app.bsky.embed.images",
"images": images,
}
if post.tags:
facets = []
for tag in post.tags:
facets.append({
"$type": "app.bsky.richtext.facet",
"features": [{
"$type": "app.bsky.richtext.facet#tag",
"tag": tag.lstrip('#'),
}],
})
record["facets"] = facets
return record
# -----------------------------------------------------------------------------
# ActivityPub (Note / Create) Translation
# -----------------------------------------------------------------------------
[docs]def activitypub_to_unified(doc: Mapping[str, Any]) -> UnifiedPost:
"""Translate an ActivityPub Note or Create activity to UnifiedPost."""
obj: Mapping[str, Any] = doc
if doc.get('type') == 'Create' and isinstance(doc.get('object'), dict):
obj = doc['object']
content_html = str(obj.get('content', ''))
text = strip_html(content_html)
author = str(obj.get('attributedTo') or doc.get('actor', ''))
pub_str = obj.get('published') or doc.get('published', '')
created_at = iso_to_unix(pub_str) if pub_str else int(time.time())
reply_to = obj.get('inReplyTo')
if isinstance(reply_to, dict):
reply_to = reply_to.get('id')
attachments: list[str] = []
raw_atts = obj.get('attachment', [])
if isinstance(raw_atts, list):
for att in raw_atts:
if isinstance(att, dict):
url = att.get('url')
if isinstance(url, dict):
url = url.get('href')
if url:
attachments.append(str(url))
tags: list[str] = []
raw_tags = obj.get('tag', [])
if isinstance(raw_tags, list):
for t in raw_tags:
if isinstance(t, dict):
name = t.get('name', '')
if name:
tags.append(name.lstrip('#').lower())
return UnifiedPost(
text=text,
author=author,
created_at=created_at,
attachments=attachments,
reply_to=str(reply_to) if reply_to else None,
tags=tags,
extra={"activitypub_id": obj.get("id") or doc.get("id")},
)
[docs]def unified_to_activitypub(
post: UnifiedPost,
domain: str = "node.fleetmesh.local",
wrap_in_create: bool = True,
) -> Mapping[str, Any]:
"""Translate UnifiedPost to an ActivityPub Note (or Create(Note))."""
obj_id = f"https://{domain}/objects/{post.extra.get('nostr_id') or post.created_at}"
author_uri = post.author if post.author.startswith("https://") else f"https://{domain}/users/{post.author or 'node'}"
note: MutableMapping[str, Any] = {
"@context": "https://www.w3.org/ns/activitystreams",
"id": obj_id,
"type": "Note",
"attributedTo": author_uri,
"content": text_to_html(post.text),
"published": unix_to_iso(post.created_at or int(time.time())),
"to": ["https://www.w3.org/ns/activitystreams#Public"],
}
if post.reply_to:
note["inReplyTo"] = post.reply_to
if post.attachments:
note["attachment"] = [
{"type": "Document", "mediaType": "image/jpeg", "url": att}
for att in post.attachments
]
if post.tags:
note["tag"] = [
{"type": "Hashtag", "name": f"#{t.lstrip('#')}"}
for t in post.tags
]
if not wrap_in_create:
return note
activity_id = f"{obj_id}/activity"
return {
"@context": "https://www.w3.org/ns/activitystreams",
"id": activity_id,
"type": "Create",
"actor": author_uri,
"published": note["published"],
"to": note["to"],
"object": note,
}
# -----------------------------------------------------------------------------
# Secure Scuttlebutt (SSB post) Translation
# -----------------------------------------------------------------------------
[docs]def ssb_to_unified(msg: Mapping[str, Any]) -> UnifiedPost:
"""Translate an SSB message document or post content to UnifiedPost."""
val = msg.get('value', msg)
content = val.get('content', msg)
text = str(content.get('text', ''))
author = str(val.get('author', ''))
ts = val.get('timestamp') or msg.get('timestamp', 0)
created_at = int(ts / 1000) if ts > 10000000000 else int(ts) or int(time.time())
reply_to = content.get('branch')
root = content.get('root')
tags: list[str] = []
channel = content.get('channel')
if channel:
tags.append(str(channel).lstrip('#').lower())
attachments: list[str] = []
mentions = content.get('mentions', [])
if isinstance(mentions, list):
for m in mentions:
if isinstance(m, dict) and m.get('link'):
attachments.append(str(m['link']))
return UnifiedPost(
text=text,
author=author,
created_at=created_at,
attachments=attachments,
reply_to=str(reply_to) if reply_to else None,
root=str(root) if root else None,
tags=tags,
extra={"ssb_key": msg.get("key")},
)
[docs]def unified_to_ssb(post: UnifiedPost) -> Mapping[str, Any]:
"""Translate UnifiedPost to an SSB post content structure."""
content: MutableMapping[str, Any] = {
"type": "post",
"text": post.text,
}
if post.root and post.reply_to and post.root != post.reply_to:
content["root"] = post.root
content["branch"] = post.reply_to
elif post.reply_to:
content["root"] = post.reply_to
content["branch"] = post.reply_to
if post.tags:
content["channel"] = post.tags[0].lstrip('#')
if post.attachments:
content["mentions"] = [{"link": att} for att in post.attachments]
return content
# -----------------------------------------------------------------------------
# p2panda (append-only operation log) Translation
# -----------------------------------------------------------------------------
[docs]def p2panda_to_unified(doc: Mapping[str, Any]) -> UnifiedPost:
"""Translate a p2panda operation dict or payload mapping to UnifiedPost."""
header = doc.get('header')
hdr_map: Mapping[str, Any] = header if isinstance(header, Mapping) else {}
raw_body = doc.get('body', doc)
body_map: Mapping[str, Any] = {}
text = ""
if isinstance(raw_body, Mapping) and raw_body is not doc:
body_map = raw_body
text = str(body_map.get('text') or body_map.get('content') or '')
elif isinstance(raw_body, (bytes, bytearray)):
decoded = bytes(raw_body).decode('utf-8', errors='replace')
text = decoded
elif isinstance(raw_body, str):
text = raw_body
else:
body_map = doc
text = str(doc.get('text') or doc.get('content') or '')
author = str(hdr_map.get('public_key') or body_map.get('author') or doc.get('author') or '')
ts = hdr_map.get('timestamp') or body_map.get('timestamp') or doc.get('created_at') or 0
created_at = int(ts) if isinstance(ts, (int, float)) and ts > 0 else int(time.time())
ext = hdr_map.get('extensions')
ext_map: Mapping[str, Any] = ext if isinstance(ext, Mapping) else {}
reply_to = body_map.get('reply_to') or ext_map.get('reply_to') or hdr_map.get('backlink')
root = body_map.get('root') or ext_map.get('root')
raw_tags = body_map.get('tags', [])
tags = [str(t).lstrip('#').lower() for t in raw_tags if isinstance(t, str)] if isinstance(raw_tags, list) else []
raw_atts = body_map.get('attachments', [])
attachments = [str(a) for a in raw_atts if isinstance(a, str)] if isinstance(raw_atts, list) else []
return UnifiedPost(
text=text,
author=author,
created_at=created_at,
attachments=attachments,
reply_to=str(reply_to) if reply_to else None,
root=str(root) if root else None,
tags=tags,
extra={"p2panda_seq": hdr_map.get("seq_num")},
)
[docs]def unified_to_p2panda(post: UnifiedPost) -> Mapping[str, Any]:
"""Translate UnifiedPost to a p2panda operation payload structure."""
payload: MutableMapping[str, Any] = {
"type": "p2panda.post",
"text": post.text,
"author": post.author,
"timestamp": post.created_at or int(time.time()),
}
if post.reply_to:
payload["reply_to"] = post.reply_to
if post.root:
payload["root"] = post.root
if post.tags:
payload["tags"] = [t.lstrip('#') for t in post.tags]
if post.attachments:
payload["attachments"] = list(post.attachments)
return payload
# -----------------------------------------------------------------------------
# Rhio (cluster message & blob sync) Translation
# -----------------------------------------------------------------------------
[docs]def rhio_to_unified(doc: Mapping[str, Any]) -> UnifiedPost:
"""Translate a Rhio cluster envelope or payload mapping to UnifiedPost."""
inner = doc.get('payload')
payload_map: Mapping[str, Any] = inner if isinstance(inner, Mapping) else doc
text = str(payload_map.get('text') or payload_map.get('content') or '')
author = str(payload_map.get('author') or doc.get('author') or '')
ts = payload_map.get('timestamp') or doc.get('timestamp') or doc.get('created_at') or 0
created_at = int(ts) if isinstance(ts, (int, float)) and ts > 0 else int(time.time())
reply_to = payload_map.get('reply_to')
root = payload_map.get('root')
raw_tags = payload_map.get('tags', [])
tags = [str(t).lstrip('#').lower() for t in raw_tags if isinstance(t, str)] if isinstance(raw_tags, list) else []
raw_atts = payload_map.get('attachments', [])
attachments = [str(a) for a in raw_atts if isinstance(a, str)] if isinstance(raw_atts, list) else []
blob_hash = payload_map.get('blob_hash') or doc.get('hash')
if isinstance(blob_hash, str) and blob_hash and blob_hash not in attachments:
attachments.append(blob_hash)
return UnifiedPost(
text=text,
author=author,
created_at=created_at,
attachments=attachments,
reply_to=str(reply_to) if reply_to else None,
root=str(root) if root else None,
tags=tags,
extra={"rhio_subject": doc.get("subject", "fleetmesh.posts")},
)
[docs]def unified_to_rhio(post: UnifiedPost, subject: str = "fleetmesh.posts") -> Mapping[str, Any]:
"""Translate UnifiedPost to a Rhio JetStream publication envelope."""
payload: MutableMapping[str, Any] = {
"type": "rhio.post",
"text": post.text,
"author": post.author,
"timestamp": post.created_at or int(time.time()),
}
if post.reply_to:
payload["reply_to"] = post.reply_to
if post.root:
payload["root"] = post.root
if post.tags:
payload["tags"] = [t.lstrip('#') for t in post.tags]
if post.attachments:
payload["attachments"] = list(post.attachments)
return {
"subject": subject,
"timestamp": payload["timestamp"],
"payload": payload,
}
# -----------------------------------------------------------------------------
# Unified Protocol Translator Matrix
# -----------------------------------------------------------------------------
[docs]class ProtocolTranslator:
"""Dispatches bidirectional translations across all supported protocols."""
INGEST_MAP = {
'nostr': nostr_to_unified,
'atproto': atproto_to_unified,
'activitypub': activitypub_to_unified,
'ssb': ssb_to_unified,
'p2panda': p2panda_to_unified,
'rhio': rhio_to_unified,
}
EMIT_MAP = {
'nostr': unified_to_nostr,
'atproto': unified_to_atproto,
'activitypub': unified_to_activitypub,
'ssb': unified_to_ssb,
'p2panda': unified_to_p2panda,
'rhio': unified_to_rhio,
}
[docs] @classmethod
def to_unified(cls, source_protocol: str, payload: Mapping[str, Any], **kwargs: Any) -> UnifiedPost:
"""Parse source protocol payload into UnifiedPost."""
proto = source_protocol.lower().strip()
if proto == 'nostr':
return nostr_to_unified(payload)
elif proto == 'atproto':
return atproto_to_unified(payload, author=kwargs.get('author', ''))
elif proto == 'activitypub':
return activitypub_to_unified(payload)
elif proto == 'ssb':
return ssb_to_unified(payload)
elif proto == 'p2panda':
return p2panda_to_unified(payload)
elif proto == 'rhio':
return rhio_to_unified(payload)
else:
raise ValueError(f"Unsupported source protocol: {source_protocol}")
[docs] @classmethod
def from_unified(cls, target_protocol: str, post: UnifiedPost, **kwargs: Any) -> Mapping[str, Any]:
"""Format UnifiedPost into target protocol payload."""
proto = target_protocol.lower().strip()
if proto == 'nostr':
return unified_to_nostr(post, pubkey=kwargs.get('pubkey'))
elif proto == 'atproto':
return unified_to_atproto(post)
elif proto == 'activitypub':
return unified_to_activitypub(
post,
domain=kwargs.get('domain', 'node.fleetmesh.local'),
wrap_in_create=kwargs.get('wrap_in_create', True),
)
elif proto == 'ssb':
return unified_to_ssb(post)
elif proto == 'p2panda':
return unified_to_p2panda(post)
elif proto == 'rhio':
return unified_to_rhio(post, subject=kwargs.get('subject', 'fleetmesh.posts'))
else:
raise ValueError(f"Unsupported target protocol: {target_protocol}")
[docs] @classmethod
def translate(
cls,
source_protocol: str,
target_protocol: str,
payload: Mapping[str, Any],
**kwargs,
) -> Mapping[str, Any]:
"""Direct translation between any two supported protocols."""
post = cls.to_unified(source_protocol, payload, **kwargs)
return cls.from_unified(target_protocol, post, **kwargs)