perf(sync): look up WorkOS user IDs through an indexed table (#50)

Finding the WP user for a WorkOS user ID (every sign-in and webhook, the WorkOS Users list, the role push) ran get_users() on the _workos_user_id meta. meta_value isn't indexed, so each lookup scanned every row with that key: ~40 ms on a site with 25,000 linked users, for hits and misses alike.

{base_prefix}workos_user_links mirrors the meta with the WorkOS ID as the key. The user meta hooks keep it in step with every write through the meta API, and the v4 schema upgrade fills it from the existing meta (25,000 rows in ~0.5 s). The meta stays the source of truth: each hit is checked against it, a stale row is repaired and answered from the meta, and lookups use the meta until the table is filled. Results match the get_users() query: users of the current site, the first by login when two carry one ID.

The WorkOS Users list resolves the whole page in two queries instead of one meta scan per row.

Author: bordoni

AGENTS.md

@@ -164,6 +164,7 @@ Per-environment constants (take priority over generic):
 | **Sync** | |
 | `src/WorkOS/Sync/Controller.php` | Sync controller |
 | `src/WorkOS/Sync/UserSync.php` | User sync (inbound/outbound) |
+| `src/WorkOS/Sync/UserLinks.php` | WorkOS user ID → WP user lookups through `{base_prefix}workos_user_links` (indexed), mirrored from the `_workos_user_id` meta by the user meta hooks and filled by the v4 schema upgrade. `find()` / `find_many()` check every hit against the meta and use the meta until the table is filled (`workos_user_links_ready`). Writes to the meta that skip the meta API (raw SQL) aren't seen; `UserLinks::rebuild()` refills. |
 | `src/WorkOS/Sync/RoleMapper.php` | WorkOS role → WP role mapping |
 | `src/WorkOS/Sync/RoleSyncCheck.php` | Which members' WP role doesn't match the role map. Batched (one JOIN query per 1,000 members), run by "Check now" on WorkOS → Users or on an Action Scheduler schedule (`role_sync_schedule`: off/hourly/daily, only offered when AS is loaded). Stores the result in `workos_role_sync_check` (not autoloaded, stale when env/org/role map change) and rechecks single users on role and `workos_org_membership_changed`. Admin screens read `result()`; nothing is computed on page load. |
 | `src/WorkOS/Sync/DirectorySync.php` | Directory sync (SCIM) |
@@ -359,6 +360,7 @@ tests/
     ├── UserHelperTest.php                          # WorkOS\User + `workos_is_sso_user`/`workos_has_active_session` helpers
     ├── UserSyncDeprovisionTest.php                 # User deprovisioning tests
     ├── UserSyncFindOrCreateTest.php                # User find-or-create tests
+    ├── UserLinksTest.php                           # Link table: follows meta writes, backfill, parity with the get_users() meta lookup, batched lookups
     ├── UserSyncLinkTest.php                        # User linking tests
     ├── UserSyncRelinkProtectionTest.php            # Re-link Protection: refuse/force/actions, sign-in, webhook, directory sync
     ├── UserSyncPushTest.php                        # Outbound user sync tests

src/WorkOS/Admin/Users/RestApi.php

@@ -8,6 +8,7 @@
 namespace WorkOS\Admin\Users;
 
 use WorkOS\Config;
+use WorkOS\Sync\UserLinks;
 use WP_Error;
 use WP_REST_Request;
 use WP_REST_Response;
@@ -170,14 +171,19 @@ public function list_users( WP_REST_Request $request ): WP_REST_Response {
 		}
 
 		$environment_id = Config::get_environment_id();
-		$users          = isset( $result['data'] ) && is_array( $result['data'] )
-			? array_map(
-				function ( $user ) use ( $environment_id ) {
-					return $this->shape_user( is_array( $user ) ? $user : [], $environment_id );
+		$rows           = isset( $result['data'] ) && is_array( $result['data'] ) ? array_filter( $result['data'], 'is_array' ) : [];
+
+		// The linked WP users for the whole page at once, not one lookup per row.
+		$wp_user_ids = UserLinks::find_many( array_map( 'strval', array_column( $rows, 'id' ) ) );
+
+		$users = array_values(
+			array_map(
+				function ( array $user ) use ( $environment_id, $wp_user_ids ) {
+					return $this->shape_user( $user, $environment_id, $wp_user_ids );
 				},
-				$result['data']
+				$rows
 			)
-			: [];
+		);
 
 		$metadata = isset( $result['list_metadata'] ) && is_array( $result['list_metadata'] )
 			? $result['list_metadata']
@@ -241,12 +247,13 @@ private function build_upstream_params( WP_REST_Request $request ): array {
 	 * profile picture URL — the list intentionally doesn't render avatars
 	 * to keep the page lean) and adds a server-computed `dashboard_url`.
 	 *
-	 * @param array  $user           Upstream user object.
-	 * @param string $environment_id Active WorkOS environment ID (for the deep link).
+	 * @param array              $user           Upstream user object.
+	 * @param string             $environment_id Active WorkOS environment ID (for the deep link).
+	 * @param array<string, int> $wp_user_ids    Linked WP user IDs by WorkOS user ID (UserLinks::find_many()).
 	 *
 	 * @return array<string, mixed>
 	 */
-	private function shape_user( array $user, string $environment_id ): array {
+	private function shape_user( array $user, string $environment_id, array $wp_user_ids ): array {
 		$id    = isset( $user['id'] ) ? (string) $user['id'] : '';
 		$email = isset( $user['email'] ) ? (string) $user['email'] : '';
 
@@ -263,20 +270,7 @@ private function shape_user( array $user, string $environment_id ): array {
 		// row can wire up the "Send password reset" trigger that lives at
 		// `POST /workos/v1/admin/users/{wp_user_id}/password-reset`. Empty
 		// when the WorkOS user has no matching WP row yet.
-		$wp_user_id = 0;
-		if ( '' !== $id ) {
-			$users = get_users(
-				[
-					'meta_key'   => '_workos_user_id',
-					'meta_value' => $id,
-					'number'     => 1,
-					'fields'     => 'ID',
-				]
-			);
-			if ( ! empty( $users ) ) {
-				$wp_user_id = (int) $users[0];
-			}
-		}
+		$wp_user_id = '' !== $id ? (int) ( $wp_user_ids[ $id ] ?? 0 ) : 0;
 
 		return [
 			'id'              => $id,

src/WorkOS/Database/Schema.php

@@ -7,6 +7,8 @@
 
 namespace WorkOS\Database;
 
+use WorkOS\Sync\UserLinks;
+
 defined( 'ABSPATH' ) || exit;
 
 /**
@@ -22,13 +24,14 @@ class Schema {
 	/**
 	 * Current schema version.
 	 */
-	private const CURRENT_VERSION = 3;
+	private const CURRENT_VERSION = 4;
 
 	/**
 	 * Activation hook — create tables.
 	 */
 	public static function activate(): void {
 		self::create_tables();
+		UserLinks::rebuild();
 		update_option( self::VERSION_OPTION, self::CURRENT_VERSION );
 	}
 
@@ -48,6 +51,9 @@ public static function maybe_upgrade(): void {
 		// is already populated, so it's safe to call on every upgrade.
 		self::migrate_active_environment_to_standalone_option();
 
+		// v4: fill the WorkOS ID → WP user table from the existing meta.
+		UserLinks::rebuild();
+
 		update_option( self::VERSION_OPTION, self::CURRENT_VERSION );
 	}
 
@@ -142,6 +148,13 @@ private static function create_tables(): void {
 			KEY idx_event_type (event_type),
 			KEY idx_user_id (user_id),
 			KEY idx_created_at (created_at)
+		) {$charset_collate};
+
+		CREATE TABLE {$wpdb->base_prefix}workos_user_links (
+			workos_user_id varchar(191) NOT NULL,
+			wp_user_id bigint(20) unsigned NOT NULL,
+			PRIMARY KEY  (workos_user_id,wp_user_id),
+			KEY idx_wp_user_id (wp_user_id)
 		) {$charset_collate};";
 
 		require_once ABSPATH . 'wp-admin/includes/upgrade.php';
@@ -159,6 +172,7 @@ public static function drop_tables(): void {
 		$wpdb->query( "DROP TABLE IF EXISTS {$wpdb->prefix}workos_org_sites" );
 		$wpdb->query( "DROP TABLE IF EXISTS {$wpdb->prefix}workos_org_memberships" );
 		$wpdb->query( "DROP TABLE IF EXISTS {$wpdb->prefix}workos_organizations" );
+		$wpdb->query( "DROP TABLE IF EXISTS {$wpdb->base_prefix}workos_user_links" );
 		// phpcs:enable
 	}
 }

src/WorkOS/Sync/Controller.php

@@ -20,6 +20,10 @@ class Controller extends BaseController {
 	 * @return void
 	 */
 	protected function doRegister(): void {
+		// First, so the link table follows every write to the link meta.
+		$this->container->singleton( UserLinks::class );
+		$this->container->get( UserLinks::class );
+
 		$this->container->singleton( UserSync::class );
 		$this->container->get( UserSync::class );
 

src/WorkOS/Sync/RoleMapper.php

@@ -438,15 +438,6 @@ public static function get_out_of_sync_user_ids(): array {
 	 * @return int|null WP user ID, or null if not found.
 	 */
 	private static function get_wp_user_by_workos_id( string $workos_id ): ?int {
-		$users = get_users(
-			[
-				'meta_key'   => '_workos_user_id',
-				'meta_value' => $workos_id,
-				'number'     => 1,
-				'fields'     => 'ID',
-			]
-		);
-
-		return ! empty( $users ) ? (int) $users[0] : null;
+		return UserLinks::find( $workos_id );
 	}
 }