Allow time to be fetched from a universal clock ⏱ #866

dpi · 2020-11-08T13:21:45Z

What a coincidence I've been putting together an OAuth project for Drupal, and in order to complete unit tests I needed a way to mock time. Thanks for the timely implementation of #852 @ramsey @kevinquinnyo

Purpose

Allow time to be fetched from a universal clock and eliminate usages of time() and strtotime() where possible.

Implementing a clock, which is useful for the Drupal Authman project. In Drupal we consider the now-time throughout the lifetime of a request to be the time at the start of the request, not the true current time. So for integration with Drupal I expect this method the proposed clock feature to be used always. For integration with other projects, its also necessary to obey time travel when other projects request it.

Implementation notes

Eliminated remaining calls to time() and strtotime() where possible. Only 2x calls to time() remain where the true current time is required for getting and testing default time.
Added \League\OAuth2\Client\Token\AccessTokenInterface::getTimeNow to interface, which was defined in Allow time to be set for test purposes #852
Rewrote comments such as "Set the time now. This should only be used for testing purposes.".
Switched tests to always simulate time where possible, to eliminate possible random test failures.
Given that the work in Allow time to be set for test purposes #852 was designed for tests only, not for public API, I defer to maintainers to whether to remove the static time method stored in \League\OAuth2\Client\Token\AccessToken::$timeNow in favor of the clock.

Clock

Inspiration for the clock comes from a few examples I'm familiar with, such as two popular Clock projects on Packagist, and Drupal.

codecov · 2020-11-08T13:22:35Z

Codecov Report

Merging #866 (d286c6a) into master (419d163) will not change coverage.
The diff coverage is 100.00%.

@@             Coverage Diff             @@
##              master      #866   +/-   ##
===========================================
  Coverage     100.00%   100.00%           
- Complexity       180       187    +7     
===========================================
  Files             20        21    +1     
  Lines            464       483   +19     
===========================================
+ Hits             464       483   +19

Impacted Files	Coverage Δ	Complexity Δ
src/Provider/AbstractProvider.php	`100.00% <100.00%> (ø)`	`67.00 <2.00> (+3.00)`
src/Provider/Clock.php	`100.00% <100.00%> (ø)`	`1.00 <1.00> (?)`
src/Token/AccessToken.php	`100.00% <100.00%> (ø)`	`30.00 <1.00> (+3.00)`

kevinquinnyo · 2020-11-09T14:41:12Z

I like it

Given that the work in #852 was designed for tests only, not for public API, I defer to maintainers to whether to remove the static time method stored in \League\OAuth2\Client\Token\AccessToken::$timeNow in favor of the clock.

IMO if this approach is taken, the static method should just be removed in favor of your approach.

It was only recently merged, so it's likely no one is utilizing this in their downstream tests (not even me and I authored the PR that added it)
It would only affect test code, not production code on the off-chance there were a BC issue.
This project already seems to have a lot of BC related juggling as-is, so it seems like a good idea not to introduce yet another one
Explicit dependency injection is usually favorable to hidden dependencies (like the static method to fake the time)

I'm not a maintainer here either, so I'll also punt, just my opinion

kevinquinnyo · 2020-11-09T14:49:42Z

src/Provider/Clock.php

+/**
+ * Represents an implementation of a Clock.
+ */
+class Clock


Is there a reason not to have something like ClockInterface here to require the now() method?

Im all for it but interfaces seem to be used sparingly on this project... I wish providers had an interface.

I think an interface is appropriate here, because the implementation of ClockInterface should be final class ....

ramsey · 2020-11-09T15:44:09Z

src/Token/AccessTokenInterface.php

+     *
+     * @return int
+     */
+    public function getTimeNow();


Both of these methods added to the interface represent a BC break.

right, of course

ramsey · 2020-11-09T15:48:28Z

src/Token/AccessTokenInterface.php

+     *
+     * @return void
+     */
+    public function setClock(Clock $clock);


Typically, we want interfaces to define things we can fetch, not necessarily how they are set. The way something is set could be left open to each implementation, but we'd want to ensure that all implementations have a way to get the clock (i.e., getClock(): Clock).

sorry, I dont understand what you're saying here. If this is about clock interfaces, im all for it.

I'm saying I would prefer to define a getClock() method on the AccessTokenInterface, rather than a setClock() method.

The changes to this interface don't make sense. An access token does not have a "clock", it has an expiry date/time. I think the only reasonable modification here would be AccessTokenInterface::getExpiresDate() that returns DateTimeImmutable. Given that getExpires returns a UNIX timestamp already, it makes no sense for the access token to have a separate clock.

ramsey · 2020-11-09T15:50:14Z

src/Token/AccessTokenInterface.php

+     *
+     * @return int
+     */
+    public function getTimeNow();


If you choose to add getClock(): Clock, and the Clock has a now(): DateTimeInterface method, then is there any reason to have getTimeNow()?

I dont see how both getTimeNow and a theoretical public getClock() method would be useful for access tokens. See also my note about whether you'd prefer for the previously implemented time functionality (getTimeNow/setTimeNow/resetTimeNow/\League\OAuth2\Client\Token\AccessToken::$timeNow) to be removed.

If you add a getClock() method, then I agree that getTimeNow() is no longer necessary.

ramsey · 2020-11-09T15:52:17Z

src/Token/AccessToken.php

+        } elseif (isset($this->clock)) {
+            return $this->clock->now()->getTimestamp();
+        } else {
+            return time();


If you implement a getClock(): Clock method that must always return a Clock, then there's no need to check for isset($this->clock). Instead, you can do:

if (self::$timeNow) { return self::$timeNow; } return $this->getClock()->now()->getTimestamp();

I think it would be better for self::$timeNow to be a DateTimeImmutable, rather than an integer.

ramsey · 2020-11-09T15:56:52Z

src/Provider/Clock.php

+   *
+   * @return \DateTimeImmutable
+   */
+    public function now()


Maybe this method should be getTime() instead of now(), so that Clock could return any DateTime object that an implementer wants to set (fixed, now, etc.)?

I used now as thats the same method implemented by the reference clock projects linked in summary. Also a getTime is strictly speaking not appropriate as you're getting more than just time.

now() is my preference.

dpi · 2020-11-10T05:57:16Z

I think a lot of this hinges on whether maintainer prefers previous time and clock to co-exist:

Remove or keep multiple time methods
Add a public getClock method? Per above I dont see a valid rationale, yet.

ramsey · 2020-11-10T17:09:17Z

Add a public getClock method? Per above I don't see a valid rationale, yet.

IMO, the rationale for a getClock() method is in your purpose statement for this:

Allow time to be fetched from a universal clock and eliminate usages of time() and strtotime() where possible

Requiring setClock() doesn't enforce anything, since any implementation could treat that as a no-op, especially since properties (i.e., protected $clock) aren't part of the contract. If we want to force implementations to respect the contract, then we need to define getClock(): Clock that must return a Clock instance. Then, wherever the Clock should be used in the parent classes, we use getClock() instead of $this->clock. The parent shouldn't care how the Clock is set, as long as getClock() returns a Clock.

shadowhand · 2021-07-17T16:42:41Z

src/Provider/Clock.php

+/**
+ * Represents an implementation of a Clock.
+ */
+class Clock


I think an interface is appropriate here, because the implementation of ClockInterface should be final class ....

shadowhand · 2021-07-17T16:43:08Z

src/Provider/Clock.php

+   *
+   * @return \DateTimeImmutable
+   */
+    public function now()


now() is my preference.

shadowhand · 2021-07-17T16:45:41Z

src/Token/AccessToken.php

+        } elseif (isset($this->clock)) {
+            return $this->clock->now()->getTimestamp();
+        } else {
+            return time();


I think it would be better for self::$timeNow to be a DateTimeImmutable, rather than an integer.

shadowhand · 2021-07-17T16:49:26Z

src/Token/AccessTokenInterface.php

+     *
+     * @return void
+     */
+    public function setClock(Clock $clock);


The changes to this interface don't make sense. An access token does not have a "clock", it has an expiry date/time. I think the only reasonable modification here would be AccessTokenInterface::getExpiresDate() that returns DateTimeImmutable. Given that getExpires returns a UNIX timestamp already, it makes no sense for the access token to have a separate clock.

shadowhand · 2021-07-17T16:50:23Z

test/src/Provider/ProgrammableClock.php

+    /**
+     * @var \DateTimeImmutable|null
+     */
+    protected $time = null;


Why wouldn't this be initialized via __construct ?

shadowhand · 2021-07-17T16:52:37Z

The goal is this PR is excellent, and I definitely support the concept of an internal clock. The implementation just needs a little work to be logical.

dpi · 2021-07-18T12:06:18Z

I dont have bandwidth or motivation to work on this right now, but i just want to make-everyone-aware of PSR-20 https://github.com/php-fig/fig-standards/blob/master/proposed/clock.md, which in summary is an interface, with a now(), method, returning a \DateTimeImmutable instance. So whatever happens here should aim to be compliant with this, which is basically a standardisation of what other clock projects have arrived at.

Because of this I see it making sense to eventually make PSR be the interface to depend on, so that could mean defining an interface here in oauth2-client, then later making the interface here extend the one from PSR-20.

kevinquinnyo · 2021-07-18T18:57:29Z

I dont have bandwidth or motivation to work on this right now

Understandable. I had a little bit of extra time this afternoon so I figured I'd take a stab at it. I've attempted to apply the code review changes as a PR to your branch @dpi here: dpi#1

@ramsey @shadowhand let me know if I've missed anything or if I'm off the mark with those changes.

I think one thing I didn't address is this comment: #866 (comment)

stof · 2023-03-29T13:54:44Z

This should use the PSR-20 ClockInterface

dpi added 2 commits November 8, 2020 20:02

Switch to fully using simulated time where possible

dbd7c83

Allow time to be fetched from a universal clock

04ccbe4

Tests an access token has the same clock as a provider.

d286c6a

dpi added a commit to dpi/authman that referenced this pull request Nov 8, 2020

prototype integration for thephpleague/oauth2-client#866

be3a56d

dpi mentioned this pull request Nov 8, 2020

Time simulation dpi/authman#1

Open

dpi added a commit to dpi/authman that referenced this pull request Nov 8, 2020

prototype integration for thephpleague/oauth2-client#866

7cc9d89

kevinquinnyo reviewed Nov 9, 2020

View reviewed changes

ramsey reviewed Nov 9, 2020

View reviewed changes

shadowhand requested changes Jul 17, 2021

View reviewed changes

kevinquinnyo mentioned this pull request Jul 18, 2021

Implement some changes based on parent branch PR review dpi/oauth2-client#1

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Allow time to be fetched from a universal clock ⏱ #866

Allow time to be fetched from a universal clock ⏱ #866

dpi commented Nov 8, 2020

codecov bot commented Nov 8, 2020 •

edited

kevinquinnyo commented Nov 9, 2020

kevinquinnyo Nov 9, 2020

dpi Nov 10, 2020

shadowhand Jul 17, 2021

ramsey Nov 9, 2020

dpi Nov 10, 2020

ramsey Nov 9, 2020

dpi Nov 10, 2020

ramsey Nov 10, 2020

shadowhand Jul 17, 2021

ramsey Nov 9, 2020

dpi Nov 10, 2020

ramsey Nov 10, 2020

ramsey Nov 9, 2020

shadowhand Jul 17, 2021

ramsey Nov 9, 2020

dpi Nov 10, 2020

shadowhand Jul 17, 2021

dpi commented Nov 10, 2020

ramsey commented Nov 10, 2020

shadowhand Jul 17, 2021

shadowhand Jul 17, 2021

shadowhand Jul 17, 2021

shadowhand Jul 17, 2021

shadowhand Jul 17, 2021

shadowhand commented Jul 17, 2021

dpi commented Jul 18, 2021

kevinquinnyo commented Jul 18, 2021

stof commented Mar 29, 2023

Allow time to be fetched from a universal clock ⏱ #866

Are you sure you want to change the base?

Allow time to be fetched from a universal clock ⏱ #866

Conversation

dpi commented Nov 8, 2020

Purpose

Implementation notes

Clock

codecov bot commented Nov 8, 2020 • edited

Codecov Report

kevinquinnyo commented Nov 9, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dpi commented Nov 10, 2020

ramsey commented Nov 10, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shadowhand commented Jul 17, 2021

dpi commented Jul 18, 2021

kevinquinnyo commented Jul 18, 2021

stof commented Mar 29, 2023

codecov bot commented Nov 8, 2020 •

edited