Skip to content

Commit 6115503

Browse files
patchandthatpatchandthat
committed
Add documentation
1 parent f346ea8 commit 6115503

14 files changed

+513
-88
lines changed

‎Rsk.AuthZen.Client/AuthZenAction.cs‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,19 @@
22

33
namespace Rsk.AuthZen.Client
44
{
5+
/// <summary>
6+
/// Represents an action in AuthZen, including its name and associated properties.
7+
/// </summary>
58
public class AuthZenAction
69
{
10+
/// <summary>
11+
/// Gets the name of the action.
12+
/// </summary>
713
public string Name { get; internal set; }
14+
15+
/// <summary>
16+
/// Gets the properties associated with the action.
17+
/// </summary>
818
public Dictionary<string, object> Properties { get; internal set; }
919
}
1020
}

‎Rsk.AuthZen.Client/AuthZenBoxcarEvaluationBody.cs‎

Lines changed: 63 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,31 @@
44

55
namespace Rsk.AuthZen.Client
66
{
7+
/// <summary>
8+
/// Represents a request body for a boxcar evaluation in AuthZen, containing multiple evaluations,
9+
/// default values, and evaluation options.
10+
/// </summary>
711
public class AuthZenBoxcarEvaluationBody
812
{
13+
/// <summary>
14+
/// Gets the list of individual evaluation bodies to be processed in the boxcar request.
15+
/// </summary>
916
public List<AuthZenEvaluationBody> Evaluations { get; internal set; }
17+
18+
/// <summary>
19+
/// Gets the default values to be applied to each evaluation if not explicitly set.
20+
/// </summary>
1021
public AuthZenEvaluationBody DefaultValues { get; internal set; }
22+
23+
/// <summary>
24+
/// Gets the options that control the semantics of the boxcar evaluation.
25+
/// </summary>
1126
public AuthZenBoxcarOptions Options { get; internal set; }
12-
27+
28+
/// <summary>
29+
/// Converts this instance to a <see cref="AuthZenBoxcarRequestMessageDto"/> for transmission.
30+
/// </summary>
31+
/// <returns>The corresponding <see cref="AuthZenBoxcarRequestMessageDto"/>.</returns>
1332
internal AuthZenBoxcarRequestMessageDto ToDto()
1433
{
1534
var dto = new AuthZenBoxcarRequestMessageDto();
@@ -53,7 +72,7 @@ internal AuthZenBoxcarRequestMessageDto ToDto()
5372
dto.Evaluations[i] = Evaluations[i].ToDto();
5473
}
5574
}
56-
75+
5776
if (Options != null)
5877
{
5978
dto.Options = Options.ToDto();
@@ -63,26 +82,58 @@ internal AuthZenBoxcarRequestMessageDto ToDto()
6382
}
6483
}
6584

85+
/// <summary>
86+
/// Represents the response from a boxcar evaluation request in AuthZen,
87+
/// including a correlation identifier and the results of individual evaluations.
88+
/// </summary>
6689
public class AuthZenBoxcarResponse
6790
{
91+
/// <summary>
92+
/// Gets the correlation identifier for the boxcar evaluation request.
93+
/// </summary>
6894
public string CorrelationId { get; internal set; }
95+
96+
/// <summary>
97+
/// Gets the list of evaluation results returned by the boxcar request.
98+
/// </summary>
6999
public List<AuthZenResponse> Evaluations { get; internal set; }
70100
}
71101

102+
/// <summary>
103+
/// Defines the semantics for boxcar evaluations in AuthZen.
104+
/// </summary>
72105
public enum BoxcarSemantics
73106
{
107+
/// <summary>
108+
/// Indicates that all evaluations should be executed.
109+
/// </summary>
74110
ExecuteAll,
111+
112+
/// <summary>
113+
/// Indicates that the evaluation should stop and deny on the first deny result.
114+
/// </summary>
75115
DenyOnFirstDeny,
116+
117+
/// <summary>
118+
/// Indicates that the evaluation should stop and permit on the first permit result.
119+
/// </summary>
76120
PermitOnFirstPermit
77121
}
78122

79-
// execute_all
80-
// deny_on_first_deny
81-
// permit_on_first_permit
123+
/// <summary>
124+
/// Represents the options for a boxcar evaluation in AuthZen, including evaluation semantics.
125+
/// </summary>
82126
public class AuthZenBoxcarOptions
83127
{
128+
/// <summary>
129+
/// Gets the semantics that control the evaluation behavior in the boxcar request.
130+
/// </summary>
84131
public BoxcarSemantics Semantics { get; internal set; }
85-
132+
133+
/// <summary>
134+
/// Converts this instance to a <see cref="AuthZenBoxcarOptionsDto"/> for transmission.
135+
/// </summary>
136+
/// <returns>The corresponding <see cref="AuthZenBoxcarOptionsDto"/>.</returns>
86137
internal AuthZenBoxcarOptionsDto ToDto()
87138
{
88139
return new AuthZenBoxcarOptionsDto
@@ -91,6 +142,12 @@ internal AuthZenBoxcarOptionsDto ToDto()
91142
};
92143
}
93144

145+
/// <summary>
146+
/// Converts the <see cref="BoxcarSemantics"/> enumeration value to its string representation.
147+
/// </summary>
148+
/// <param name="semantics">The semantics to convert.</param>
149+
/// <returns>The string representation of the semantics.</returns>
150+
/// <exception cref="ArgumentException">Thrown if the semantics value is not supported.</exception>
94151
private static string ConvertSemantics(BoxcarSemantics semantics)
95152
{
96153
return semantics switch

‎Rsk.AuthZen.Client/AuthZenClient.cs‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,18 @@
1111

1212
namespace Rsk.AuthZen.Client
1313
{
14+
/// <summary>
15+
/// Provides configuration options for the <see cref="AuthZenClient"/>.
16+
/// </summary>
1417
public class AuthZenClientOptions
1518
{
19+
/// <summary>
20+
/// Gets or sets the base URL of the AuthZen authorization service.
21+
/// </summary>
1622
public string AuthorizationUrl { get; set; }
1723
}
1824

25+
/// <inheritdoc cref="IAuthZenClient"/>
1926
public class AuthZenClient : IAuthZenClient
2027
{
2128
private const string AuthZenContentType = "application/json";
@@ -32,6 +39,13 @@ public class AuthZenClient : IAuthZenClient
3239
DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
3340
};
3441

42+
/// <summary>
43+
/// Creates a new instance of <see cref="AuthZenClient"/>.
44+
/// </summary>
45+
/// <param name="httpClientFactory">The httpClientFactory</param>
46+
/// <param name="options">The AuthZenClientOptions</param>
47+
/// <exception cref="ArgumentNullException">Thrown if any argument is null</exception>
48+
/// <exception cref="ArgumentException">Thrown if the AuthZenClientOptions are invalid</exception>
3549
public AuthZenClient(IHttpClientFactory httpClientFactory, IOptions<AuthZenClientOptions> options)
3650
{
3751
if (httpClientFactory == null) throw new ArgumentNullException(nameof(httpClientFactory));
@@ -42,6 +56,7 @@ public AuthZenClient(IHttpClientFactory httpClientFactory, IOptions<AuthZenClien
4256
httpClient.BaseAddress = new Uri(options.Value.AuthorizationUrl);
4357
}
4458

59+
/// <inheritdoc cref="IAuthZenClient"/>
4560
public async Task<AuthZenResponse> Evaluate(AuthZenEvaluationRequest request)
4661
{
4762
var requestMessage = new HttpRequestMessage(HttpMethod.Post, new Uri($"{UriBase}/{EvaluationUri}", UriKind.Relative));
@@ -79,6 +94,7 @@ public async Task<AuthZenResponse> Evaluate(AuthZenEvaluationRequest request)
7994
return authZenResponse;
8095
}
8196

97+
/// <inheritdoc cref="IAuthZenClient"/>
8298
public async Task<AuthZenBoxcarResponse> Evaluate(AuthZenBoxcarEvaluationRequest request)
8399
{
84100
if (IsMultiEvaluationsMissing(request))

‎Rsk.AuthZen.Client/AuthZenEvaluationBody.cs‎

Lines changed: 26 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,39 @@
33

44
namespace Rsk.AuthZen.Client
55
{
6+
/// <summary>
7+
/// Represents the body of an evaluation request in AuthZen, including subject, resource, action, and context.
8+
/// </summary>
69
public class AuthZenEvaluationBody
710
{
11+
/// <summary>
12+
/// Gets the subject for the evaluation request.
13+
/// </summary>
814
public AuthZenSubject Subject { get; internal set; }
15+
16+
/// <summary>
17+
/// Gets the resource for the evaluation request.
18+
/// </summary>
919
public AuthZenResource Resource { get; internal set; }
20+
21+
/// <summary>
22+
/// Gets the action to be evaluated.
23+
/// </summary>
1024
public AuthZenAction Action { get; internal set; }
25+
26+
/// <summary>
27+
/// Gets the context data for the evaluation request.
28+
/// </summary>
1129
public Dictionary<string, object> Context { get; internal set; }
1230

31+
/// <summary>
32+
/// Converts this instance to a <see cref="AuthZenRequestMessageDto"/> for transmission.
33+
/// </summary>
34+
/// <returns>The corresponding <see cref="AuthZenRequestMessageDto"/>.</returns>
1335
internal AuthZenRequestMessageDto ToDto()
1436
{
1537
var dto = new AuthZenRequestMessageDto();
16-
38+
1739
if (Subject != null)
1840
{
1941
dto.Subject = new AuthZenSubjectDto
@@ -23,7 +45,7 @@ internal AuthZenRequestMessageDto ToDto()
2345
Properties = Subject.Properties
2446
};
2547
}
26-
48+
2749
if (Resource != null)
2850
{
2951
dto.Resource = new AuthZenResourceDto
@@ -33,7 +55,7 @@ internal AuthZenRequestMessageDto ToDto()
3355
Properties = Resource.Properties
3456
};
3557
}
36-
58+
3759
if (Action != null)
3860
{
3961
dto.Action = new AuthZenActionDto
@@ -42,7 +64,7 @@ internal AuthZenRequestMessageDto ToDto()
4264
Properties = Action.Properties
4365
};
4466
}
45-
67+
4668
dto.Context = Context;
4769

4870
return dto;

‎Rsk.AuthZen.Client/AuthZenRequestFailureException.cs‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,31 @@
22

33
namespace Rsk.AuthZen.Client
44
{
5+
/// <summary>
6+
/// Represents an error that occurs when a request to the AuthZen service fails.
7+
/// </summary>
58
public class AuthZenRequestFailureException : Exception
69
{
10+
/// <summary>
11+
/// Initializes a new instance of the <see cref="AuthZenRequestFailureException"/> class.
12+
/// </summary>
713
public AuthZenRequestFailureException()
814
{
915
}
10-
16+
17+
/// <summary>
18+
/// Initializes a new instance of the <see cref="AuthZenRequestFailureException"/> class with a specified error message.
19+
/// </summary>
20+
/// <param name="message">The error message</param>
1121
public AuthZenRequestFailureException(string message) : base(message)
1222
{
1323
}
1424

25+
/// <summary>
26+
/// Initializes a new instance of the <see cref="AuthZenRequestFailureException"/> class with a specified error message and a reference to the inner exception that is the cause of this exception.
27+
/// <param name="message">The error message</param>
28+
/// <param name="inner">The inner exception</param>
29+
/// </summary>
1530
public AuthZenRequestFailureException(string message, Exception inner) : base(message, inner)
1631
{
1732
}

‎Rsk.AuthZen.Client/AuthZenResource.cs‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,24 @@
22

33
namespace Rsk.AuthZen.Client
44
{
5+
/// <summary>
6+
/// Represents a resource in an AuthZen evaluation request, including its identifier, type, and additional properties.
7+
/// </summary>
58
public class AuthZenResource
69
{
10+
/// <summary>
11+
/// Gets the unique identifier of the resource.
12+
/// </summary>
713
public string Id { get; internal set; }
14+
15+
/// <summary>
16+
/// Gets the type of the resource.
17+
/// </summary>
818
public string Type { get; internal set; }
19+
20+
/// <summary>
21+
/// Gets additional properties associated with the resource.
22+
/// </summary>
923
public Dictionary<string, object> Properties { get; internal set; }
1024
}
1125
}

‎Rsk.AuthZen.Client/AuthZenResponse.cs‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,23 @@
11
namespace Rsk.AuthZen.Client
22
{
3+
/// <summary>
4+
/// Represents the response from an AuthZen evaluation, including the decision, context, and correlation identifier.
5+
/// </summary>
36
public class AuthZenResponse
47
{
8+
/// <summary>
9+
/// Gets the decision result of the evaluation.
10+
/// </summary>
511
public Decision Decision { get; internal set; }
12+
13+
/// <summary>
14+
/// Gets the context information associated with the evaluation response.
15+
/// </summary>
616
public string Context { get; internal set; }
17+
18+
/// <summary>
19+
/// Gets the correlation identifier for tracking the evaluation request and response.
20+
/// </summary>
721
public string CorrelationId { get; internal set; }
822
}
923
}

0 commit comments

Comments
 (0)