Skip to content

Commit a3bc892

Browse files
mortenpimortenpi
committed
bring back docs/internals.md
1 parent 93f6b59 commit a3bc892

File tree

2 files changed

+80
-77
lines changed

2 files changed

+80
-77
lines changed

‎README.md‎

Lines changed: 1 addition & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -66,80 +66,4 @@ julia> Pkg.Registry.update()
6666

6767
## Implementation
6868

69-
Authentication is implemented with the following state machine:
70-
71-
```mermaid
72-
---
73-
title: PkgAuthentication state machine diagram
74-
---
75-
76-
stateDiagram-v2
77-
direction LR
78-
79-
[*] --> NeedAuthentication
80-
81-
NeedAuthentication --> HasToken
82-
NeedAuthentication --> NoAuthentication
83-
note right of NeedAuthentication
84-
Checks if a syntactically valid auth.toml token file
85-
exists for the requested server (but does not check
86-
whether it has expired or not). Proceeds to HasToken
87-
if it exists, or NoAuthentication if not.
88-
end note
89-
90-
HasToken --> NeedRefresh
91-
HasToken --> Success
92-
note right of HasToken
93-
If the token is valid (i.e. not expired, based on the
94-
expiry times in the auth.toml file), proceeds to Success.
95-
Otherwise, proceeds to NeedRefresh.
96-
end note
97-
98-
NeedRefresh --> NoAuthentication
99-
NeedRefresh --> HasNewToken
100-
NeedRefresh --> Failure
101-
note right of NeedRefresh
102-
Attempts to acquire a new access token by using the refresh
103-
token in the auth.toml. If the refresh succeeds, it will
104-
proceed to HasNewToken, or to NoAuthentication if it fails.
105-
end note
106-
107-
NoAuthentication --> RequestLogin
108-
NoAuthentication --> Failure
109-
note right of NoAuthentication
110-
Attempts to acquire an OAuth challenge from the Pkg server.
111-
If successful, proceeds to RequestLogin, or to Failure
112-
otherwise.
113-
end note
114-
115-
HasNewToken --> HasNewToken
116-
HasNewToken --> Success
117-
HasNewToken --> Failure
118-
note right of HasNewToken
119-
Takes the token from the previous step and writes it to the
120-
auth.toml file. In order to handle potential race conditions
121-
with other writes, it will check that the write was succeful,
122-
and will try again if it fails. If the write was successful,
123-
it proceeds to Success, or retries HasNewToken if it was not.
124-
May proceed to Failure if there is an unexpected failure.
125-
end note
126-
127-
RequestLogin --> ClaimToken
128-
RequestLogin --> Failure
129-
note right of RequestLogin
130-
Presents the in-browser step of the OAuth authentication process
131-
to the user (e.g. by opening the Pkg server's login page in the
132-
user's browser). Proceeds to ClaimToken immediately, or to Failure
133-
if there was an unexpected failure.
134-
end note
135-
136-
ClaimToken --> ClaimToken
137-
ClaimToken --> HasNewToken
138-
ClaimToken --> Failure
139-
note right of ClaimToken
140-
Starts polling the Pkg server's OAuth token claiming endpoint,
141-
returning to ClaimToken while the polling is happening. Proceeds
142-
to HasNewToken if it successfully acquires a token, or to Failure
143-
if the polling times out, or there is an unexpected error.
144-
end note
145-
```
69+
For implementation details, please see [`docs/internals.md`](docs/internals.md).

‎docs/internals.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Implementation notes
2+
3+
The authentication control flow is implemented as the following state machine, starting from the `NeedAuthentication` state, and finish in either `Success` or `Failure`.
4+
5+
```mermaid
6+
---
7+
title: PkgAuthentication state machine diagram
8+
---
9+
10+
stateDiagram-v2
11+
direction LR
12+
13+
[*] --> NeedAuthentication
14+
15+
NeedAuthentication --> HasToken
16+
NeedAuthentication --> NoAuthentication
17+
note right of NeedAuthentication
18+
Checks if a syntactically valid auth.toml token file
19+
exists for the requested server (but does not check
20+
whether it has expired or not). Proceeds to HasToken
21+
if it exists, or NoAuthentication if not.
22+
end note
23+
24+
HasToken --> NeedRefresh
25+
HasToken --> Success
26+
note right of HasToken
27+
If the token is valid (i.e. not expired, based on the
28+
expiry times in the auth.toml file), proceeds to Success.
29+
Otherwise, proceeds to NeedRefresh.
30+
end note
31+
32+
NeedRefresh --> NoAuthentication
33+
NeedRefresh --> HasNewToken
34+
NeedRefresh --> Failure
35+
note right of NeedRefresh
36+
Attempts to acquire a new access token by using the refresh
37+
token in the auth.toml. If the refresh succeeds, it will
38+
proceed to HasNewToken, or to NoAuthentication if it fails.
39+
end note
40+
41+
NoAuthentication --> RequestLogin
42+
NoAuthentication --> Failure
43+
note right of NoAuthentication
44+
Attempts to acquire an OAuth challenge from the Pkg server.
45+
If successful, proceeds to RequestLogin, or to Failure
46+
otherwise.
47+
end note
48+
49+
HasNewToken --> HasNewToken
50+
HasNewToken --> Success
51+
HasNewToken --> Failure
52+
note right of HasNewToken
53+
Takes the token from the previous step and writes it to the
54+
auth.toml file. In order to handle potential race conditions
55+
with other writes, it will check that the write was succeful,
56+
and will try again if it fails. If the write was successful,
57+
it proceeds to Success, or retries HasNewToken if it was not.
58+
May proceed to Failure if there is an unexpected failure.
59+
end note
60+
61+
RequestLogin --> ClaimToken
62+
RequestLogin --> Failure
63+
note right of RequestLogin
64+
Presents the in-browser step of the OAuth authentication process
65+
to the user (e.g. by opening the Pkg server's login page in the
66+
user's browser). Proceeds to ClaimToken immediately, or to Failure
67+
if there was an unexpected failure.
68+
end note
69+
70+
ClaimToken --> ClaimToken
71+
ClaimToken --> HasNewToken
72+
ClaimToken --> Failure
73+
note right of ClaimToken
74+
Starts polling the Pkg server's OAuth token claiming endpoint,
75+
returning to ClaimToken while the polling is happening. Proceeds
76+
to HasNewToken if it successfully acquires a token, or to Failure
77+
if the polling times out, or there is an unexpected error.
78+
end note
79+
```

0 commit comments

Comments
 (0)