Accessing headers to see rate limits

[PaulWebster]

I am experimenting with blueskysdk - thanks for building it.
While testing I have been hit with a rate limit error from Bluesky. I had not posted much the content was mostly the same and I was deleting them by hand ... so perhaps I triggered some sort of bot protection at their end.
However, I cannot see what rate limits are being applied.
Their documentation suggest that there is more information in the HTTP headers.
Is there a way I can get the extra information via your API or do I have to edit your source to put more diagnostics in there?

[shahmal1yev]

Hi @PaulWebster,

Thanks for reaching out and starting this discussion!

If you want the truth, this can be handled quite easily. I had anticipated this might be necessary and implemented a method to handle headers: RequestHandler.php#L68

With just a few small adjustments, this functionality can be added.

Diff

diff --git a/src/Lexicons/Traits/RequestHandler.php b/src/Lexicons/Traits/RequestHandler.php
index dd0b6f6..03ea58b 100644
--- a/src/Lexicons/Traits/RequestHandler.php
+++ b/src/Lexicons/Traits/RequestHandler.php
@@ -26,7 +26,10 @@ trait RequestHandler
         $this->request();
         $this->handle();
 
-        return $this->content;
+        return [
+            $this->content,
+            $this->responseHeaders,
+        ];
     }
 
     /**
diff --git a/src/Responses/BaseResponse.php b/src/Responses/BaseResponse.php
index da5afdd..67aadcc 100644
--- a/src/Responses/BaseResponse.php
+++ b/src/Responses/BaseResponse.php
@@ -10,10 +10,11 @@ use Atproto\Traits\Castable;
 trait BaseResponse
 {
     protected array $content = [];
+    protected array $headers = [];
 
-    public function __construct(array $content)
+    public function __construct(array $response)
     {
-        $this->content = $content;
+        [$this->content, $this->headers] = $response;
     }
 
     /**
@@ -58,6 +59,29 @@ trait BaseResponse
         return $this->parse($offset);
     }
 
+    public function headers(): array
+    {
+        return $this->headers;
+    }
+
+    /**
+     * @param  string  $name
+     * @param mixed $defaultValue
+     * @return mixed
+     */
+    public function header(string $name, $defaultValue = null)
+    {
+        if (array_key_exists($name, $this->headers)) {
+            return $this->headers[$name];
+        }
+
+        if (is_callable($defaultValue)) {
+            return $defaultValue($this);
+        }
+
+        return $defaultValue;
+    }
+
     public function resolve($name)
     {
         return @$this->get($name);
diff --git a/tests/Unit/Lexicons/App/Bsky/Actor/GetProfilesTest.php b/tests/Unit/Lexicons/App/Bsky/Actor/GetProfilesTest.php
index 3812c8d..983024a 100644
--- a/tests/Unit/Lexicons/App/Bsky/Actor/GetProfilesTest.php
+++ b/tests/Unit/Lexicons/App/Bsky/Actor/GetProfilesTest.php
@@ -87,7 +87,7 @@ class GetProfilesTest extends TestCase
 
     public function testResourceMethodReturnsCorrectInstance(): void
     {
-        $data = ['actors' => []];
+        $data = [['actors' => []], []];
         $resource = $this->request->response($data);
         $this->assertInstanceOf(GetProfilesResponse::class, $resource, 'Resource method should return an instance of GetProfilesResource.');
     }
diff --git a/tests/Unit/Responses/BaseResponseTest.php b/tests/Unit/Responses/BaseResponseTest.php
index f6bb926..94382b4 100644
--- a/tests/Unit/Responses/BaseResponseTest.php
+++ b/tests/Unit/Responses/BaseResponseTest.php
@@ -19,7 +19,8 @@ class BaseResponseTest extends TestCase
         parent::setUp();
 
         $this->resource = new TestableResponse([
-            'example' => 'some value',
+            ['example' => 'some value',],
+            ['foo' => 'bar']
         ]);
     }
 
@@ -50,6 +51,35 @@ class BaseResponseTest extends TestCase
         $this->assertInstanceOf(ExampleObject::class, $result);
     }
 
+    public function testHeaderIsAccessible(): void
+    {
+        $this->assertSame('bar', $this->resource->header('foo'));
+    }
+
+    public function testHeadersMethodReturnsArray(): void
+    {
+        $this->assertIsArray($headers = $this->resource->headers());
+        $this->assertArrayHasKey('foo', $headers);
+        $this->assertNotEmpty($headers);
+    }
+
+    public function testHeaderMethodReturnsNullWhenHeaderNotFound(): void
+    {
+        $this->assertNull($this->resource->header('nonexistent'));
+    }
+
+    public function testHeaderMethodReturnsDefaultValueWhenHeaderNotFound(): void
+    {
+        $this->assertSame('default value', $this->resource->header(
+            'nonexistent',
+            'default value'
+        ));
+
+        $this->assertInstanceOf(ExampleObject::class, $this->resource->header(
+            'nonexistent',
+            static fn (ResponseContract $response): ExampleObject => $response->resolve('example')
+        ));
+    }
 }
 
 class TestableResponse implements ResponseContract

That said, I also want to try a few things that came to mind to:

• Verify there are no issues with the current interface.
• Ensure the newly introduced interface is the best alternative.
• Test it in real scenarios and evaluate the outcomes.

I’d also love to hear your thoughts on this topic—it could be really helpful.

Give me a little time for these checks, and I’ll send you a notification as soon as the release is ready.

[PaulWebster]

Thanks for this.
I will try it out - however, while I was waiting for Bluesky to expire my rate limit, I had time to try another PHP library. It has less features than yours but had a call available to ask for the headers from the last call.
A benefit of that approach for backward compatibility is that if you did the same then the response would be unchanged for your current users - and those who want the headers could make the extra call when needed.

So I used that and I could see that Bluesky had put a 24 hour pause on me for making 10 Auth calls in about 1 hour of my testing. I thought that was quite severe from them but perhaps they expected refresh tokens to be used or they apply hard limits for new appkey usage. Anyway ... the other PHP library has the possibility to configure a refresh token which it stores, reuses and refreshes ... so once my rate-limit expired I switched to that and have not had any issues so far.

[shahmal1yev]

Thanks for sharing this!

This really seems like a great feature, but I must admit that I’m not entirely sure I fully understand it. As far as I know, this library sends only one token request per runtime, and if I’m mistaken about this, it might indicate a bug you’ve discovered. Additionally, are you saying that the library you mentioned provides a way to save tokens and their expiration times somewhere after the first runtime, allowing them to be reused in subsequent runtimes? Or is it something entirely different?

[PaulWebster]

I was testing in single shot ... a basic web page that I could call to post a test message.
I assumed that each try resulted in a new auth request but I did not look deeply.

The API that I was referring to is from cjrasmussen
The auth call in that API has 2 or 3 parameters - if 3 then extra is the path to the token file.
I do not see a date with the token but it is opaque.
I had a quick look at the code and I think it uses token if available and if it fails then it switches to id/pass (and stores token on success).

[shahmal1yev]

Yes, I came across this yesterday while reviewing the README.md file of a new repository on your account. A try... catch... block clarified everything. I’ve made a few commits based on it and am continuing to work on it. It looks promising, and I believe something good will come out of this.

[shahmal1yev]

Here it is, I think it's done now: https://github.com/shahmal1yev/blueskysdk/blob/36c02cdf6992f788c902c1041645b12689c83b9f/tests/Feature/SessionManagementTest.php

I will publish a blog post about this after the release. Thanks for your contribution, @PaulWebster. I will note this in the release notes.

[PaulWebster]

Thanks for doing this.
I plan to try it out over the coming few days.

[shahmal1yev]

You're welcome! I'm glad to hear you'll give it a try in the coming days. Please don't hesitate to reach out if you encounter any issues or have feedback—I'd be happy to assist or make improvements based on your experience.

In the meantime, I'll mark this discussion as temporarily closed. Feel free to reopen it or start a new one if needed. Thanks again for your contribution! 🚀

[PaulWebster]

I just tried the session handling and that worked well. I simply saved the token to a text file - and set savedtoken to NULL first ever time (no saved token available) through so that I did not have to have both a 2 and 3 parameter call.

[shahmal1yev]

Yes, if you want to use existing sessions, this is the recommended way to do it. In the first call, considering that there might not be an existing session, the third parameter can take a null value, and in this case, it creates a new session using the credentials.