Replace tuple with RecordsBySubject struct

Replace (String, Vec<RecordId>) tuples with a proper
RecordsBySubject struct throughout the many-to-many query
implementation as Lexicons per ATProto spec do not offer a tuple type.

Add lexicon definition for the getManyToMany XRPC endpoint.

constellation/src/lib.rs

···
     }
 }
 
+#[derive(Debug, PartialEq, Serialize, Deserialize, Clone, Default)]
+pub struct RecordsBySubject {
+    pub subject: String,
+    pub records: Vec<RecordId>,
+}
+
 /// maybe the worst type in this repo, and there are some bad types
 #[derive(Debug, Serialize, PartialEq)]
 pub struct CountsByCount {

constellation/src/server/mod.rs

···
 use tokio_util::sync::CancellationToken;
 
 use crate::storage::{LinkReader, StorageStats};
-use crate::{CountsByCount, Did, RecordId};
+use crate::{CountsByCount, Did, RecordId, RecordsBySubject};
 
 mod acceptable;
 mod filters;
···
 #[derive(Template, Serialize)]
 #[template(path = "get-many-to-many.html.j2")]
 struct GetManyToManyItemsResponse {
-    linking_records: Vec<(String, Vec<RecordId>)>,
+    linking_records: Vec<RecordsBySubject>,
     cursor: Option<OpaqueApiCursor>,
     #[serde(skip_serializing)]
     query: GetManyToManyItemsQuery,

constellation/src/storage/mem_store.rs

···
 use super::{
     LinkReader, LinkStorage, PagedAppendingCollection, PagedOrderedCollection, StorageStats,
 };
-use crate::{ActionableEvent, CountsByCount, Did, RecordId};
+use crate::{ActionableEvent, CountsByCount, Did, RecordId, RecordsBySubject};
 use anyhow::Result;
 use links::CollectedLink;
 use std::collections::{HashMap, HashSet};
···
         after: Option<String>,
         filter_dids: &HashSet<Did>,
         filter_to_targets: &HashSet<String>,
-    ) -> Result<PagedOrderedCollection<(String, Vec<RecordId>), String>> {
+    ) -> Result<PagedOrderedCollection<RecordsBySubject, String>> {
         let empty_res = Ok(PagedOrderedCollection {
             items: Vec::new(),
             next: None,
···
 
         let mut items = grouped_links
             .into_iter()
-            .map(|(t, r)| (t.0, r))
+            .map(|(t, r)| RecordsBySubject {
+                subject: t.0,
+                records: r,
+            })
             .collect::<Vec<_>>();
 
-        items.sort_by(|(a, _), (b, _)| a.cmp(b));
+        items.sort_by(|a, b| a.subject.cmp(&b.subject));
 
         items = items
             .into_iter()
-            .skip_while(|(t, _)| after.as_ref().map(|a| t <= a).unwrap_or(false))
+            .skip_while(|item| after.as_ref().map(|a| &item.subject <= a).unwrap_or(false))
             .take(limit as usize)
             .collect();
 
         let next = if items.len() as u64 >= limit {
-            items.last().map(|(t, _)| t.clone())
+            items.last().map(|item| item.subject.clone())
         } else {
             None
         };

constellation/src/storage/mod.rs

···
-use crate::{ActionableEvent, CountsByCount, Did, RecordId};
+use crate::{ActionableEvent, CountsByCount, Did, RecordId, RecordsBySubject};
 use anyhow::Result;
 use serde::{Deserialize, Serialize};
 use std::collections::{HashMap, HashSet};
···
         after: Option<String>,
         filter_dids: &HashSet<Did>,
         filter_to_targets: &HashSet<String>,
-    ) -> Result<PagedOrderedCollection<(String, Vec<RecordId>), String>>;
+    ) -> Result<PagedOrderedCollection<RecordsBySubject, String>>;
 
     fn get_all_counts(
         &self,
···
                 &HashSet::new(),
             )?,
             PagedOrderedCollection {
-                items: vec![(
-                    "b.com".to_string(),
-                    vec![RecordId {
+                items: vec![RecordsBySubject {
+                    subject: "b.com".to_string(),
+                    records: vec![RecordId {
                         did: "did:plc:asdf".into(),
                         collection: "app.t.c".into(),
                         rkey: "asdf".into(),
                     }]
-                )],
+                }],
                 next: None,
             }
         );
···
         assert_eq!(result.items.len(), 2);
         assert_eq!(result.next, None);
         // Find b.com group
-        let (b_target, b_records) = result.items.iter().find(|(target, _)| target == "b.com").unwrap();
-        assert_eq!(b_target, "b.com");
-        assert_eq!(b_records.len(), 2);
-        assert!(b_records.iter().any(|r| r.did.0 == "did:plc:asdf" && r.rkey == "asdf"));
-        assert!(b_records.iter().any(|r| r.did.0 == "did:plc:asdf" && r.rkey == "asdf2"));
+        let b_group = result
+            .items
+            .iter()
+            .find(|group| group.subject == "b.com")
+            .unwrap();
+        assert_eq!(b_group.subject, "b.com");
+        assert_eq!(b_group.records.len(), 2);
+        assert!(b_group.records
+            .iter()
+            .any(|r| r.did.0 == "did:plc:asdf" && r.rkey == "asdf"));
+        assert!(b_group.records
+            .iter()
+            .any(|r| r.did.0 == "did:plc:asdf" && r.rkey == "asdf2"));
         // Find c.com group
-        let (c_target, c_records) = result.items.iter().find(|(target, _)| target == "c.com").unwrap();
-        assert_eq!(c_target, "c.com");
-        assert_eq!(c_records.len(), 2);
-        assert!(c_records.iter().any(|r| r.did.0 == "did:plc:fdsa" && r.rkey == "fdsa"));
-        assert!(c_records.iter().any(|r| r.did.0 == "did:plc:fdsa" && r.rkey == "fdsa2"));
+        let c_group = result
+            .items
+            .iter()
+            .find(|group| group.subject == "c.com")
+            .unwrap();
+        assert_eq!(c_group.subject, "c.com");
+        assert_eq!(c_group.records.len(), 2);
+        assert!(c_group.records
+            .iter()
+            .any(|r| r.did.0 == "did:plc:fdsa" && r.rkey == "fdsa"));
+        assert!(c_group.records
+            .iter()
+            .any(|r| r.did.0 == "did:plc:fdsa" && r.rkey == "fdsa2"));
 
         // Test with DID filter - should only get records from did:plc:fdsa
         let result = storage.get_many_to_many(
···
             &HashSet::new(),
         )?;
         assert_eq!(result.items.len(), 1);
-        let (target, records) = &result.items[0];
-        assert_eq!(target, "c.com");
-        assert_eq!(records.len(), 2);
-        assert!(records.iter().all(|r| r.did.0 == "did:plc:fdsa"));
+        let group = &result.items[0];
+        assert_eq!(group.subject, "c.com");
+        assert_eq!(group.records.len(), 2);
+        assert!(group.records.iter().all(|r| r.did.0 == "did:plc:fdsa"));
 
         // Test with target filter - should only get records linking to b.com
         let result = storage.get_many_to_many(
···
             &HashSet::from_iter(["b.com".to_string()]),
         )?;
         assert_eq!(result.items.len(), 1);
-        let (target, records) = &result.items[0];
-        assert_eq!(target, "b.com");
-        assert_eq!(records.len(), 2);
-        assert!(records.iter().all(|r| r.did.0 == "did:plc:asdf"));
+        let group = &result.items[0];
+        assert_eq!(group.subject, "b.com");
+        assert_eq!(group.records.len(), 2);
+        assert!(group.records.iter().all(|r| r.did.0 == "did:plc:asdf"));
     });
 }

constellation/src/storage/rocks_store.rs

···
     ActionableEvent, LinkReader, LinkStorage, PagedAppendingCollection, PagedOrderedCollection,
     StorageStats,
 };
-use crate::{CountsByCount, Did, RecordId};
+use crate::{CountsByCount, Did, RecordId, RecordsBySubject};
 use anyhow::{bail, Result};
 use bincode::Options as BincodeOptions;
 use links::CollectedLink;
···
         after: Option<String>,
         filter_dids: &HashSet<Did>,
         filter_to_targets: &HashSet<String>,
-    ) -> Result<PagedOrderedCollection<(String, Vec<RecordId>), String>> {
+    ) -> Result<PagedOrderedCollection<RecordsBySubject, String>> {
         let collection = Collection(collection.to_string());
         let path = RPath(path.to_string());
 
···
             }
         }
 
-        let mut items: Vec<(String, Vec<RecordId>)> = Vec::with_capacity(grouped_links.len());
+        let mut items: Vec<RecordsBySubject> = Vec::with_capacity(grouped_links.len());
         for (fwd_target_id, records) in &grouped_links {
             let Some(target_key) = self
                 .target_id_table
···
 
             let target_string = target_key.0 .0;
 
-            items.push((target_string, records.clone()));
+            items.push(RecordsBySubject {
+                subject: target_string,
+                records: records.clone(),
+            });
         }
 
         let next = if grouped_links.len() as u64 >= limit {

constellation/templates/get-many-to-many.html.j2

···
 
   <h3>Many-to-many links, most recent first:</h3>
 
-  {% for (target, records) in linking_records %}
-    <h4>Target: <code>{{ target }}</code> <small>(<a href="/links/all?target={{ target|urlencode }}">view all links</a>)</small></h4>
-    {% for record in records %}
+  {% for group in linking_records %}
+    <h4>Target: <code>{{ group.subject }}</code> <small>(<a href="/links/all?target={{ group.subject|urlencode }}">view all links</a>)</small></h4>
+    {% for record in group.records %}
       <pre style="display: block; margin: 1em 2em" class="code"><strong>DID</strong>:        {{ record.did().0 }}
 <strong>Collection</strong>: {{ record.collection }}
 <strong>RKey</strong>:       {{ record.rkey }}

lexicons/blue.microcosm/links/getManyToMany.json

···
+{
+	"lexicon": 1,
+	"id": "blue.microcosm.links.getManyToMany",
+	"defs": {
+		"main": {
+			"type": "query",
+			"description": "Get records that link to a primary subject, grouped by the secondary subjects they also reference",
+			"parameters": {
+				"type": "params",
+				"required": ["subject", "source", "pathToOther"],
+				"properties": {
+					"subject": {
+						"type": "string",
+						"format": "uri",
+						"description": "the primary target being linked to (at-uri, did, or uri)"
+					},
+					"source": {
+						"type": "string",
+						"description": "collection and path specification for the primary link (e.g., 'app.bsky.feed.like:subject.uri')"
+					},
+					"pathToOther": {
+						"type": "string",
+						"description": "path to the secondary link in the many-to-many record (e.g., 'otherThing.uri')"
+					},
+					"did": {
+						"type": "array",
+						"description": "filter links to those from specific users",
+						"items": {
+							"type": "string",
+							"format": "did"
+						}
+					},
+					"otherSubject": {
+						"type": "array",
+						"description": "filter secondary links to specific subjects",
+						"items": {
+							"type": "string"
+						}
+					},
+					"limit": {
+						"type": "integer",
+						"minimum": 1,
+						"maximum": 100,
+						"default": 16,
+						"description": "number of results to return"
+					}
+				}
+			},
+			"output": {
+				"encoding": "application/json",
+				"schema": {
+					"type": "object",
+					"required": ["linking_records"],
+					"properties": {
+						"linking_records": {
+							"type": "array",
+							"items": {
+								"type": "ref",
+								"ref": "#recordsBySubject"
+							}
+						},
+						"cursor": {
+							"type": "string",
+							"description": "pagination cursor"
+						}
+					}
+				}
+			}
+		},
+		"recordsBySubject": {
+			"type": "object",
+			"required": ["subject", "records"],
+			"properties": {
+				"subject": {
+					"type": "string",
+					"description": "the secondary subject that these records link to"
+				},
+				"records": {
+					"type": "array",
+					"items": {
+						"type": "ref",
+						"ref": "#linkRecord"
+					}
+				}
+			}
+		},
+		"linkRecord": {
+			"type": "object",
+			"required": ["did", "collection", "rkey"],
+			"description": "A record identifier consisting of a DID, collection, and record key",
+			"properties": {
+				"did": {
+					"type": "string",
+					"format": "did",
+					"description": "the DID of the linking record's repository"
+				},
+				"collection": {
+					"type": "string",
+					"format": "nsid",
+					"description": "the collection of the linking record"
+				},
+				"rkey": {
+					"type": "string",
+					"format": "record-key"
+				}
+			}
+		}
+	}
+}