api docs for many-to-many counts

Author: uniphil

constellation/src/server/filters.rs

@@ -22,3 +22,7 @@ pub fn to_browseable(s: &str) -> askama::Result<Option<String>> {
 pub fn human_number(n: &u64) -> askama::Result<String> {
     Ok(n.to_formatted_string(&Locale::en))
 }
+
+pub fn to_u64(n: usize) -> askama::Result<u64> {
+    Ok(n as u64)
+}

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

@@ -2,11 +2,62 @@
 {% import "try-it-macros.html.j2" as try_it %}
 
 {% block title %}Many to Many counts{% endblock %}
-{% block description %}All {{ query.source }} records with links to {{ query.subject }}{% endblock %}
+{% block description %}Counts of many-to-many {{ query.source }} join records with links to {{ query.subject }} and a secondary target at {{ query.path_to_other }}{% endblock %}
 
 {% block content %}
 
-  (todo)
+  {% call try_it::get_many_to_many_counts(
+    query.subject,
+    query.source,
+    query.path_to_other,
+    query.did,
+    query.other_subject,
+    query.limit,
+  ) %}
+
+  <h2>
+    Many-to-many links to <code>{{ query.subject }}</code> joining through <code>{{ query.path_to_other }}</code>
+    {% if let Some(browseable_uri) = query.subject|to_browseable %}
+      <small style="font-weight: normal; font-size: 1rem"><a href="{{ browseable_uri }}">browse record</a></small>
+    {% endif %}
+  </h2>
+
+  <p><strong>{% if cursor.is_some() || query.cursor.is_some() %}more than {% endif %}{{ counts_by_other_subject.len()|to_u64|human_number }} joins</strong> <code>{{ query.source }}→{{ query.path_to_other }}</code></p>
+
+  <ul>
+    <li>See direct backlinks at <code>/xrpc/blue.microcosm.links.getBacklinks</code>: <a href="/xrpc/blue.microcosm.links.getBacklinks?subject={{ query.subject|urlencode }}&source={{ query.source|urlencode }}">/xrpc/blue.microcosm.links.getBacklinks?subject={{ query.subject }}&source={{ query.source }}</a></li>
+    <li>See all links to this target at <code>/links/all</code>: <a href="/links/all?target={{ query.subject|urlencode }}">/links/all?target={{ query.subject }}</a></li>
+  </ul>
+
+  <h3>Counts by other subject:</h3>
+
+  {% for counts in counts_by_other_subject %}
+    <pre style="display: block; margin: 1em 2em" class="code"><strong>Joined subject</strong>:    {{ counts.subject }}
+<strong>Joining records</strong>:   {{ counts.total }}
+<strong>Unique joiner ids</strong>: {{ counts.distinct }}
+-> {% if let Some(browseable_uri) = counts.subject|to_browseable -%}
+    <a href="{{ browseable_uri }}">browse record</a>
+  {%- endif %}</pre>
+  {% endfor %}
+
+  {% if let Some(c) = cursor %}
+    <form method="get" action="/xrpc/blue.microcosm.links.getManyToManyCounts">
+      <input type="hidden" name="subject" value="{{ query.subject }}" />
+      <input type="hidden" name="source" value="{{ query.source }}" />
+      <input type="hidden" name="pathToOther" value="{{ query.path_to_other }}" />
+      {% for did in query.did %}
+        <input type="hidden" name="did" value="{{ did }}" />
+      {% endfor %}
+      {% for otherSubject in query.other_subject %}
+        <input type="hidden" name="otherSubject" value="{{ otherSubject }}" />
+      {% endfor %}
+      <input type="hidden" name="limit" value="{{ query.limit }}" />
+      <input type="hidden" name="cursor" value={{ c|json|safe }} />
+      <button type="submit">next page&hellip;</button>
+    </form>
+  {% else %}
+    <button disabled><em>end of results</em></button>
+  {% endif %}
 
   <details>
     <summary>Raw JSON response</summary>

constellation/templates/hello.html.j2

@@ -55,6 +55,32 @@
   {% call try_it::get_backlinks("at://did:plc:a4pqq234yw7fqbddawjo7y35/app.bsky.feed.post/3m237ilwc372e", "app.bsky.feed.like:subject.uri", [""], 16) %}
 
 
+  <h3 class="route"><code>GET /xrpc/blue.microcosm.links.getManyToManyCounts</code></h3>
+
+  <p>TODO: description</p>
+
+  <h4>Query parameters:</h4>
+
+  <ul>
+    <li><p><code>subject</code>: required, must url-encode. Example: <code>at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r</code></p></li>
+    <li><p><code>source</code>: required. Example: <code>app.bsky.feed.like:subject.uri</code></p></li>
+    <li><p><code>pathToOther</code>: required. Path to the secondary link in the many-to-many record. Example: <code>otherThing.uri</code></p></li>
+    <li><p><code>did</code>: optional, filter links to those from specific users. Include multiple times to filter by multiple users. Example: <code>did=did:plc:vc7f4oafdgxsihk4cry2xpze&did=did:plc:vc7f4oafdgxsihk4cry2xpze</code></p></li>
+    <li><p><code>otherSubject</code>: optional, filter secondary links to specific subjects. Include multiple times to filter by multiple users. Example: <code>at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r</code></p></li>
+    <li><p><code>limit</code>: optional. Default: <code>16</code>. Maximum: <code>100</code></p></li>
+  </ul>
+
+  <p style="margin-bottom: 0"><strong>Try it:</strong></p>
+  {% call try_it::get_many_to_many_counts(
+    "at://did:plc:a4pqq234yw7fqbddawjo7y35/app.bsky.feed.post/3m237ilwc372e",
+    "app.bsky.feed.like:subject.uri",
+    "otherThing.uri",
+    [""],
+    [""],
+    16,
+  ) %}
+
+
   <h3 class="route"><code>GET /links</code></h3>
 
   <p>A list of records linking to a target.</p>

constellation/templates/try-it-macros.html.j2

@@ -1,6 +1,6 @@
 {% macro get_backlinks(subject, source, dids, limit) %}
   <form method="get" action="/xrpc/blue.microcosm.links.getBacklinks">
-    <pre class="code"><strong>GET</strong> /links
+    <pre class="code"><strong>GET</strong> /xrpc/blue.microcosm.links.getBacklinks
   ?subject=    <input type="text" name="subject" value="{{ subject }}" placeholder="at-uri, did, uri..." />
   &source=     <input type="text" name="source" value="{{ source }}" placeholder="app.bsky.feed.like:subject.uri" />
   {%- for did in dids %}{% if !did.is_empty() %}
@@ -24,6 +24,48 @@
   </script>
 {% endmacro %}
 
+{% macro get_many_to_many_counts(subject, source, pathToOther, dids, otherSubjects, limit) %}
+  <form method="get" action="/xrpc/blue.microcosm.links.getManyToManyCounts">
+    <pre class="code"><strong>GET</strong> /xrpc/blue.microcosm.links.getManyToManyCounts
+  ?subject=      <input type="text" name="subject" value="{{ subject }}" placeholder="at-uri, did, uri..." />
+  &source=       <input type="text" name="source" value="{{ source }}" placeholder="app.bsky.feed.like:subject.uri" />
+  &pathToOther=  <input type="text" name="pathToOther" value="{{ pathToOther }}" placeholder="otherThing.uri" />
+  {%- for did in dids %}{% if !did.is_empty() %}
+  &did=          <input type="text" name="did" value="{{ did }}" placeholder="did:plc:..." />{% endif %}{% endfor %}
+  <span id="m2m-subject-placeholder"></span>               <button id="m2m-add-subject">+ other subject filter</button>
+  {%- for otherSubject in otherSubjects %}{% if !otherSubject.is_empty() %}
+  &otherSubject= <input type="text" name="did" value="{{ otherSubject }}" placeholder="at-uri, did, uri..." />{% endif %}{% endfor %}
+  <span id="m2m-did-placeholder"></span>               <button id="m2m-add-did">+ did filter</button>
+  &limit=        <input type="number" name="limit" value="{{ limit }}" max="100" placeholder="100" /> <button type="submit">get links</button></pre>
+  </form>
+  <script>
+    const m2mAddDidButton = document.getElementById('m2m-add-did');
+    const m2mDidPlaceholder = document.getElementById('m2m-did-placeholder');
+    m2mAddDidButton.addEventListener('click', e => {
+      e.preventDefault();
+      const i = document.createElement('input');
+      i.placeholder = 'did:plc:...';
+      i.name = "did"
+      const p = m2mAddDidButton.parentNode;
+      p.insertBefore(document.createTextNode('&did=          '), m2mDidPlaceholder);
+      p.insertBefore(i, m2mDidPlaceholder);
+      p.insertBefore(document.createTextNode('\n  '), m2mDidPlaceholder);
+    });
+    const m2mAddSubjectButton = document.getElementById('m2m-add-subject');
+    const m2mSubjectPlaceholder = document.getElementById('m2m-subject-placeholder');
+    m2mAddSubjectButton.addEventListener('click', e => {
+      e.preventDefault();
+      const i = document.createElement('input');
+      i.placeholder = 'at-uri, did, uri...';
+      i.name = "otherSubject"
+      const p = m2mAddSubjectButton.parentNode;
+      p.insertBefore(document.createTextNode('&otherSubject= '), m2mSubjectPlaceholder);
+      p.insertBefore(i, m2mSubjectPlaceholder);
+      p.insertBefore(document.createTextNode('\n  '), m2mSubjectPlaceholder);
+    });
+  </script>
+{% endmacro %}
+
 {% macro links(target, collection, path, dids, limit) %}
   <form method="get" action="/links">
     <pre class="code"><strong>GET</strong> /links