Enhance profile and UUID route handling by introducing username support; refactor identifier parsing and improve error handling

Author: Leon-JavaScript

pages/defaultPage.html

@@ -21,7 +21,7 @@ <h2>Route: /uuid/&#123;username|uuid&#125;</h2>
         </article>
 
         <article class="card">
-          <h2>Route: /profile/&#123;uuid&#125;</h2>
+          <h2>Route: /profile/&#123;username|uuid&#125;</h2>
           <div>Usage:</div>
           <pre><code>__PROFILE_USAGE__</code></pre>
           <div>Example response (jeb_):</div>
@@ -43,7 +43,7 @@ <h2>Error behavior</h2>
             <tr>
               <td>400</td>
               <td>BAD_REQUEST</td>
-              <td>Missing identifier on <code class="inline">/uuid</code> or invalid UUID format on <code class="inline">/profile/&#123;uuid&#125;</code>.</td>
+              <td>Missing identifier on <code class="inline">/uuid</code> or <code class="inline">/profile</code>.</td>
             </tr>
             <tr>
               <td>404</td>

pages/defaultPage.js

@@ -85,7 +85,7 @@ export function serveDefaultPage(request) {
     const html = htmlSource
         .replace("/*__INLINE_CSS__*/", cssSource)
         .replace("__UUID_USAGE__", escapeHtml(`${base}/uuid/jeb_\n${base}/uuid/853c80ef3c3749fdaa49938b674adae6`))
-        .replace("__PROFILE_USAGE__", escapeHtml(`${base}/profile/853c80ef3c3749fdaa49938b674adae6`))
+        .replace("__PROFILE_USAGE__", escapeHtml(`${base}/profile/jeb_\n${base}/profile/853c80ef3c3749fdaa49938b674adae6`))
         .replace("__UUID_EXAMPLE__", renderJson(UUID_EXAMPLE))
         .replace("__PROFILE_EXAMPLE__", renderJson(PROFILE_EXAMPLE));
 

routes/profileRoute.js

@@ -1,13 +1,12 @@
 import { CACHE_TTL_SECONDS, STATUS } from "../config/constants";
-import { fetchSessionProfile } from "../services/minecraftApi";
+import { fetchSessionProfile, lookupByUsername } from "../services/minecraftApi";
 import { getCachedEntry, setCachedEntry } from "../utils/cache";
 import { badRequest, internalError, jsonResponse, notFound } from "../utils/responses";
 import {
   buildCacheMeta,
   decodeBase64Json,
-  isUuid,
-  normalizeUuid,
-  nowSeconds
+  nowSeconds,
+  parseUsernameOrUuid
 } from "../utils/utils";
 
 function uuidNameKey(username) {
@@ -61,12 +60,14 @@ async function cacheIdentityPayload(env, payload) {
 }
 
 export async function handleProfileRoute(identifier, env) {
-  if (!identifier || !isUuid(identifier.trim())) {
-    return badRequest("Invalid uuid format");
+  const parsed = parseUsernameOrUuid(identifier);
+  if (!parsed.ok) {
+    return badRequest(parsed.message);
   }
 
-  const normalizedUuid = normalizeUuid(identifier.trim());
-  const cacheKey = uuidIdKey(normalizedUuid);
+  const cacheKey = parsed.kind === "uuid"
+    ? uuidIdKey(parsed.normalizedUuid)
+    : uuidNameKey(parsed.username);
 
   const cached = await getCachedEntry(env, cacheKey);
   if (isValidCachedProfile(cached)) {
@@ -76,7 +77,23 @@ export async function handleProfileRoute(identifier, env) {
   }
 
   try {
-    const upstream = await fetchSessionProfile(normalizedUuid);
+    let resolvedId = parsed.kind === "uuid" ? parsed.normalizedUuid : null;
+
+    // If a username key is already cached without profile, skip an extra lookup.
+    if (!resolvedId && cached?.payload?.id) {
+      resolvedId = cached.payload.id;
+    }
+
+    if (!resolvedId) {
+      const identityUpstream = await lookupByUsername(parsed.username);
+      if (identityUpstream.notFound) {
+        return notFound("Player profile not found");
+      }
+
+      resolvedId = identityUpstream.data.id;
+    }
+
+    const upstream = await fetchSessionProfile(resolvedId);
     if (upstream.notFound) {
       return notFound("Player profile not found");
     }

routes/uuidRoute.js

@@ -1,7 +1,7 @@
 import { CACHE_TTL_SECONDS, STATUS } from "../config/constants";
 import { getCachedEntry, setCachedEntry } from "../utils/cache";
 import { badRequest, internalError, jsonResponse, notFound } from "../utils/responses";
-import { buildCacheMeta, isUuid, normalizeUuid, nowSeconds } from "../utils/utils";
+import { buildCacheMeta, nowSeconds, parseUsernameOrUuid } from "../utils/utils";
 import { lookupByUsername, lookupByUuid } from "../services/minecraftApi";
 
 function uuidNameKey(username) {
@@ -41,14 +41,14 @@ async function cacheIdentityPayload(env, payload) {
 }
 
 export async function handleUuidRoute(identifier, env) {
-  if (!identifier) {
-    return badRequest("Missing username or uuid");
+  const parsed = parseUsernameOrUuid(identifier);
+  if (!parsed.ok) {
+    return badRequest(parsed.message);
   }
 
-  const input = identifier.trim();
-  const inputIsUuid = isUuid(input);
-  const normalizedUuid = inputIsUuid ? normalizeUuid(input) : null;
-  const cacheKey = inputIsUuid ? uuidIdKey(normalizedUuid) : uuidNameKey(input);
+  const cacheKey = parsed.kind === "uuid"
+    ? uuidIdKey(parsed.normalizedUuid)
+    : uuidNameKey(parsed.username);
 
   const cached = await getCachedEntry(env, cacheKey);
   if (isValidCachedIdentity(cached)) {
@@ -58,9 +58,9 @@ export async function handleUuidRoute(identifier, env) {
   }
 
   try {
-    const upstream = inputIsUuid
-      ? await lookupByUuid(normalizedUuid)
-      : await lookupByUsername(input);
+    const upstream = parsed.kind === "uuid"
+      ? await lookupByUuid(parsed.normalizedUuid)
+      : await lookupByUsername(parsed.username);
 
     if (upstream.notFound) {
       return notFound("Player not found");

utils/utils.js

@@ -9,6 +9,39 @@ export function normalizeUuid(value) {
   return value.toLowerCase().replace(/-/g, "");
 }
 
+export function parseUsernameOrUuid(identifier) {
+  if (typeof identifier !== "string") {
+    return {
+      ok: false,
+      message: "Missing username or uuid"
+    };
+  }
+
+  const value = identifier.trim();
+  if (!value) {
+    return {
+      ok: false,
+      message: "Missing username or uuid"
+    };
+  }
+
+  if (isUuid(value)) {
+    return {
+      ok: true,
+      kind: "uuid",
+      value,
+      normalizedUuid: normalizeUuid(value)
+    };
+  }
+
+  return {
+    ok: true,
+    kind: "username",
+    value,
+    username: value
+  };
+}
+
 export function nowSeconds() {
   return Math.floor(Date.now() / 1000);
 }