fix(sync): address review feedback on scoping, sync failure handling, and docs

Author: kishore7snehil

UPGRADING.md

@@ -16,7 +16,8 @@ Check that your environment is compatible with 6.0's requirements before upgradi
 
 Update your customizations, if necessary:
 
-- **No changes are required for the plugin's built-in features.** Login, logout, the callback handler, user session handling, and the User Sync background jobs continue to work as they did in 5.x. The settings stored in the WordPress admin are unchanged.
+- **No changes are required for the plugin's built-in features.** Login, logout, the callback handler, and user session handling continue to work as they did in 5.x. The settings stored in the WordPress admin are unchanged.
+- **User Sync now retries a failed event instead of always discarding it.** In 5.x a sync event that failed at the Management API was dropped from the queue regardless of the reason. In 6.x, a transient failure (an HTTP 429 rate limit, a 5xx server error, or a network error) keeps the event in the queue so the next cron pass retries it. Permanent failures (such as an HTTP 400 from an invalid profile) are still dropped, since retrying them would never succeed. No configuration change is needed, but a queue that previously drained to empty on every pass may now hold a retrying event until it succeeds.
 - **Custom code that calls the Management API has changed.** In v9 the old `wpAuth0()->getSdk()->management()` entry point is non-functional and will throw a `TypeError`. Use the new `wpAuth0()->getManagement()` accessor instead. It builds a Management client from the Domain, Client ID, and Client Secret you already configure in the plugin settings, and fetches and caches a client credentials token for you automatically.
 
   ```php
@@ -41,8 +42,9 @@ Update your customizations, if necessary:
 
 - If your custom code calls the Management API directly, review the [auth0-php v9 migration guide](https://github.com/auth0/auth0-php/blob/v9/v9_MIGRATION_GUIDE.md) for the full set of changes. The most common adjustments are:
   - Sub-resources are reached by property access, not method calls: `->users->list()` rather than `->users()->getAll()`.
+  - `users->list()` returns a `Pager` you iterate with `foreach`. It is a lazy iterator that makes further requests as you consume it, so `count()` and array access will not behave the way a plain array would.
   - Responses are typed objects instead of raw PSR-7 responses. Call `$response->jsonSerialize()` to get the same snake_case array the v8 `HttpResponse::decodeContent()` returned, or use the typed getters (`$response->getEmail()`).
   - Errors throw exceptions. A non-2xx response raises `Auth0\SDK\API\Management\Exceptions\Auth0ApiException` (use `getCode()` for the HTTP status), and transport-level failures raise `Auth0\SDK\API\Management\Exceptions\Auth0Exception`. There is no more `HttpResponse::wasSuccessful()` check.
   - Request parameters are camelCase typed objects. For example, creating a user takes a `CreateUserRequestContent` whose keys are `givenName` and `familyName` (not `given_name` / `family_name`), and the `connection` is set inside that object rather than passed as a separate argument.
-  - Listing users only returns the paginated envelope when `includeTotals` is set to `true`. Omitting it yields an empty result, so pass `'includeTotals' => true` when you page through users.
+  - The `includeTotals` parameter only controls whether the response envelope carries the count fields (`total`, `start`, `limit`, `length`). It defaults to `true` and does not affect whether users are returned, so you get results either way.
   - Some ticket methods were renamed: `tickets()->createPasswordChange()` is now `tickets->changePassword()`, and `tickets()->createEmailVerification()` is now `tickets->verifyEmail()`. The user id moves inside the request object as `userId`.

scoper.inc.php

@@ -83,11 +83,16 @@
         '/^update_/',
         '/^delete_/',
         '/^set_/',
+        // WordPress globals not matched by the prefixes above.
+        'checked',
+        'maybe_create_table',
+        'nocache_headers',
+        'submit_button',
     ],
 
-	'expose-global-constants' => true,
-	'expose-global-classes'   => true,
-	'expose-global-functions' => true,
+	'expose-global-constants' => false,
+	'expose-global-classes'   => false,
+	'expose-global-functions' => false,
 
     'patchers' => [],
 ];

src/Actions/Sync.php

@@ -9,6 +9,7 @@
 use Auth0\SDK\API\Management\Users\Requests\{CreateUserRequestContent, ListUsersByEmailRequestParameters, UpdateUserRequestContent};
 use Auth0\WordPress\Database;
 use JsonSerializable;
+use Psr\Http\Client\ClientExceptionInterface;
 use Throwable;
 use WP_User;
 
@@ -198,7 +199,7 @@ public function getDatabaseName(?string $dbConnection): ?string
         static $dbConnectionName = [];
 
         if (isset($dbConnectionName[$dbConnection])) {
-            return $dbConnectionName[$dbConnectionName];
+            return $dbConnectionName[$dbConnection];
         }
 
         if (null !== $dbConnection) {
@@ -221,6 +222,11 @@ public function onBackgroundMaintenance(): void
 
     public function onBackgroundSync(): void
     {
+        // Leave the queue intact until configured, rather than failing per item.
+        if (! $this->isPluginReady()) {
+            return;
+        }
+
         $database = $this->getPlugin()->database();
         $table = $database->getTableName(Database::CONST_TABLE_SYNC);
         $network = get_current_network_id();
@@ -256,14 +262,24 @@ public function onBackgroundSync(): void
                             $this->eventUserUpdated($dbConnection, $payload);
                         }
                     }
-                } catch (Throwable $throwable) {
-                    // A single failed item must not abort draining the rest of
-                    // the queue; the row is still removed below to avoid a
-                    // poison message blocking the queue indefinitely.
-                    try {
-                        error_log($throwable->getMessage());
-                    } catch (Throwable) {
+                } catch (Auth0ApiException $auth0ApiException) {
+                    $status = $auth0ApiException->getCode();
+
+                    // Keep the row for the next cron pass on transient failures.
+                    if (429 === $status || $status >= 500) {
+                        error_log($auth0ApiException->getMessage());
+
+                        continue;
                     }
+
+                    error_log($auth0ApiException->getMessage());
+                } catch (ClientExceptionInterface $clientException) {
+                    // Transport failures are transient, so keep the row for retry.
+                    error_log($clientException->getMessage());
+
+                    continue;
+                } catch (Throwable $throwable) {
+                    error_log($throwable->getMessage());
                 }
             }
 

src/Filters/Base.php

@@ -4,6 +4,7 @@
 
 namespace Auth0\WordPress\Filters;
 
+use Auth0\SDK\API\Management\Wrapper\ManagementClient;
 use Auth0\SDK\Auth0;
 use Auth0\WordPress\Plugin;
 
@@ -44,6 +45,11 @@ final public function getPriority(string $event, int $default = 10, string $pref
         return $default;
     }
 
+    final public function getManagement(): ManagementClient
+    {
+        return $this->plugin->getManagement();
+    }
+
     final public function getSdk(): Auth0
     {
         return $this->plugin->getSdk();

src/Plugin.php

@@ -195,6 +195,7 @@ public function getManagement(): ManagementClient
                 : null;
 
             $this->management = new ManagementClient(new ManagementClientOptions(
+                // Management always uses the tenant domain, not a custom domain, for its audience and token endpoint.
                 domain: (string) $configuration->getDomain(),
                 clientId: $configuration->getClientId(),
                 clientSecret: $configuration->getClientSecret(),