Skip to content

Commit dfd3417

Browse files
vbilopavvbilopav
committed
Improve documentations and comments
1 parent 1563022 commit dfd3417

7 files changed

Lines changed: 295 additions & 165 deletions

File tree

‎NpgsqlRest/Auth/NpgsqlRestAuthenticationOptions.cs‎

Lines changed: 25 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -105,33 +105,48 @@ public class NpgsqlRestAuthenticationOptions
105105
public string? PasswordVerificationSucceededCommand { get; set; } = null;
106106

107107
/// <summary>
108-
/// Set user context to true for all requests.
109-
/// When this is set to true, user information (user id, user name and user roles) will be set to the context variables.
110-
/// You can set this individually for each request.
108+
/// Enable setting authenticated user claims to context variables automatically.
109+
/// See ContextKeyClaimsMapping and ClaimsJsonContextKey options.
110+
/// You can set this individually for each request by using UserContext endpoint property or user_context comment annotation.
111111
/// </summary>
112112
public bool UseUserContext { get; set; } = false;
113113

114-
public Dictionary<string, string> ContextKeyClaimsMapping { get; set; } = new()
114+
/// <summary>
115+
/// Mapping of context keys to user claim names.
116+
/// Keys are the context variable names and values are the user claim names.
117+
/// When <see cref="UseUserContext"/> is enabled, the user claims from will be automatically mapped to the context variables.
118+
/// </summary>
119+
public Dictionary<string, string> ContextKeyClaimsMapping { get; set; } = new()
115120
{
116121
{ "request.user_id", "user_id" },
117122
{ "request.user_name", "user_name" },
118123
{ "request.user_roles" , "user_roles" },
119124
};
120125

126+
/// <summary>
127+
/// Context key that is used to set context variable for all available user claims.
128+
/// When this option is not null, and user is authenticated, the user claims will be serialized to JSON value and set to the context variable.
129+
/// </summary>
121130
public string? ClaimsJsonContextKey { get; set; } = null;
122131

123132
/// <summary>
124133
/// IP address context key that is used to set context variable for the IP address.
134+
/// When this option is not null, the IP address will be set to the context variable when <see cref="UseUserContext"/> is enabled and even when user is not authenticated.
125135
/// </summary>
126136
public string? IpAddressContextKey { get; set; } = "request.ip_address";
127137

128138
/// <summary>
129-
/// Set user parameters to true for all requests.
130-
/// When this is set to true, user information (user id, user name and user roles) will be set to the matching parameter names if available.
131-
/// You can set this individually for each request.
139+
/// Enable mapping authenticated user claims to parameters by name automatically.
140+
/// See ParameterNameClaimsMapping and ClaimsJsonParameterName options.
141+
/// You can set this individually for each request by using UseUserParameters endpoint property or user_parameters comment annotation.
132142
/// </summary>
133143
public bool UseUserParameters { get; set; } = false;
134144

145+
/// <summary>
146+
/// Mapping of parameter names to user claim names.
147+
/// Keys are the parameter names and values are the user claim names.
148+
/// When <see cref="UseUserParameters"/> is enabled, the user claims from will be automatically mapped to the parameters.
149+
/// </summary>
135150
public Dictionary<string, string> ParameterNameClaimsMapping { get; set; } = new()
136151
{
137152
{ "_user_id" , "user_id" },
@@ -140,18 +155,14 @@ public class NpgsqlRestAuthenticationOptions
140155
};
141156

142157
/// <summary>
143-
/// All user claims will be serialized to JSON value and set to the parameter with this name.
158+
/// Parameter name that is used to set value for all available user claims.
159+
/// When this option is not null, and user is authenticated, the user claims will be serialized to JSON value and set to the parameter with this name.
144160
/// </summary>
145161
public string? ClaimsJsonParameterName { get; set; } = "_user_claims";
146162

147163
/// <summary>
148164
/// IP address parameter name that is used to set parameter value for the IP address.
149-
/// Parameter name can be original or converted and it has to be the text type.
165+
/// When this option is not null, the IP address will be set to the parameter when <see cref="UseUserContext"/> is enabled and even when user is not authenticated.
150166
/// </summary>
151167
public string? IpAddressParameterName { get; set; } = "_ip_address";
152-
153-
///// <summary>
154-
///// All user claims will be serialized to JSON value and set to the parameter with this name.
155-
///// </summary>
156-
//public string? UserClaimsParameterName { get; set; } = "_user_claims";
157168
}

‎NpgsqlRest/Defaults/DefaultCommentParser.cs‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -150,9 +150,7 @@ internal static class DefaultCommentParser
150150
];
151151

152152
private static readonly string[] userContextKey = [
153-
"user_context",
154-
"user_settings",
155-
"user_config"
153+
"user_context"
156154
];
157155

158156
private static readonly string[] userParemetersKey = [
@@ -737,8 +735,6 @@ internal static class DefaultCommentParser
737735
}
738736

739737
// user_context
740-
// user_settings
741-
// user_config
742738
else if (haveTag is true && StrEqualsToArray(words[0], userContextKey))
743739
{
744740
routineEndpoint.UserContext = true;

‎NpgsqlRest/NpgsqlRestOptions.cs‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,7 @@ public NpgsqlRestOptions(NpgsqlDataSource dataSource)
103103
public string? UrlPathPrefix { get; set; } = "/api";
104104

105105
/// <summary>
106-
/// Custom function delegate that receives routine and options parameters and returns constructed URL path string for routine. Default is the default URL builder that transforms snake case names to kebab case names.
106+
/// Custom function delegate that receives routine and options parameters and returns constructed URL path string for routine. Default the default URL builder that transforms snake case names to kebab case names.
107107
/// </summary>
108108
public Func<Routine, NpgsqlRestOptions, string> UrlPathBuilder { get; set; } = DefaultUrlBuilder.CreateUrl;
109109

@@ -200,7 +200,12 @@ public NpgsqlRestOptions(NpgsqlDataSource dataSource)
200200
public CommentsMode CommentsMode { get; set; } = CommentsMode.OnlyWithHttpTag;
201201

202202
/// <summary>
203-
/// Configure how to send request headers to PostgreSQL routines execution. `Ignore` (default) doesn't send any request headers to routines. `Context` sets a context variable for the current session `context.headers` containing JSON string with current request headers. This executes `set_config('context.headers', headers, false)` before any routine executions. `Parameter` sends request headers to the routine parameter defined with the `RequestHeadersParameterName` option. Parameter with this name must exist, must be one of the JSON or text types and must have the default value defined. This option for individual endpoints can be changed with the `EndpointCreated` function callback, or by using comment annotations.
203+
/// Configure how to send request headers to PostgreSQL routines execution:
204+
/// - `Ignore` (default) don't send any request headers to routines.
205+
/// - `Context` sets a context variable for the current session `context.headers` containing JSON string with current request headers. This executes `set_config('context.headers', headers, false)` before any routine executions.
206+
/// - `Parameter` sends request headers to the routine parameter defined with the `RequestHeadersParameterName` option. Parameter with this name must exist, must be one of the JSON or text types and must have the default value defined.
207+
///
208+
/// This option for individual endpoints can be changed with the `EndpointCreated` function callback, or by using comment annotations.
204209
/// </summary>
205210
public RequestHeadersMode RequestHeadersMode { get; set; } = RequestHeadersMode.Ignore;
206211

‎NpgsqlRest/NpgsqlRestUploadOptions.cs‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,19 @@ namespace NpgsqlRest;
88
/// </summary>
99
public class NpgsqlRestUploadOptions
1010
{
11+
/// <summary>
12+
/// Enables upload functionality.
13+
/// </summary>
1114
public bool Enabled { get; set; } = true;
15+
16+
/// <summary>
17+
/// When true, logs upload events.
18+
/// </summary>
1219
public bool LogUploadEvent { get; set; } = true;
20+
21+
/// <summary>
22+
/// Log upload parameter values.
23+
/// </summary>
1324
public bool LogUploadParameters { get; set; } = false;
1425

1526
/// <summary>

0 commit comments

Comments
 (0)