Source code for fleetmesh_node.planes.services.gateway.translate

"""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)