Skip to content

Commit ab76d66

Browse files
Umang01-hashUmang01-hash
committed
Merge branch 'main' of github.com:gofr-dev/gofr
2 parents f3632d7 + 35ce371 commit ab76d66

31 files changed

+1621
-253
lines changed

Diff for: ‎.github/workflows/go.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -329,7 +329,7 @@ jobs:
329329
# Install the linting tool
330330
- name: Install golangci-lint
331331
run: |
332-
go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.62
332+
go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.64
333333
334334
- name: Get dependencies
335335
run: |

Diff for: ‎README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -137,4 +137,4 @@ If your PR is merged, or if you contribute by writing articles or promoting GoFr
137137

138138
### Partners
139139

140-
<img src="https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.png" alt="JetBrains logo" width="200">
140+
<img src="https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.png" alt="JetBrains logo" width="200">

Diff for: ‎docs/advanced-guide/debugging/page.md

+161
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# Using `pprof` in GoFr Applications
2+
3+
In GoFr applications, `pprof` profiling is automatically enabled. The profiling endpoints are served on the `METRICS_PORT`, which defaults to `2121` if not specified.
4+
5+
This guide explains how to enable and use `pprof` in GoFr applications.
6+
7+
---
8+
9+
## Enabling `pprof` in GoFr
10+
11+
### Prerequisites
12+
Ensure the `METRICS_PORT` is set (default is `2121`):
13+
```bash
14+
METRICS_PORT=2121
15+
```
16+
17+
GoFr automatically registers the following `pprof` routes:
18+
- `/debug/pprof/cmdline`
19+
- `/debug/pprof/profile`
20+
- `/debug/pprof/symbol`
21+
- `/debug/pprof/trace`
22+
- `/debug/pprof/` (index)
23+
24+
---
25+
26+
## Accessing `pprof` Endpoints
27+
28+
Once `pprof` is enabled, you can access the profiling endpoints at `http://localhost:<METRICS_PORT>/debug/pprof/`. For example, if `METRICS_PORT` is `2121`, the endpoints will be available at:
29+
- `http://localhost:2121/debug/pprof/`
30+
31+
### Available Endpoints
32+
1. **`/debug/pprof/cmdline`**:
33+
- Returns the command-line arguments of the running application.
34+
35+
2. **`/debug/pprof/profile`**:
36+
- Generates a CPU profile for the application.
37+
38+
3. **`/debug/pprof/symbol`**:
39+
- Resolves program counters into function names.
40+
41+
4. **`/debug/pprof/trace`**:
42+
- Captures an execution trace of the application.
43+
44+
5. **`/debug/pprof/` (index)**:
45+
- Provides an index page with links to all available profiling endpoints, including memory, goroutine, and blocking profiles.
46+
47+
---
48+
49+
## Collecting Profiling Data
50+
51+
### 1. **CPU Profiling**
52+
To collect a CPU profile:
53+
```bash
54+
curl -o cpu.pprof http://localhost:2121/debug/pprof/profile
55+
```
56+
57+
### 2. **Memory Profiling**
58+
To collect a memory profile:
59+
```bash
60+
curl -o mem.pprof http://localhost:2121/debug/pprof/heap
61+
```
62+
63+
### 3. **Goroutine Profiling**
64+
To collect information about running goroutines:
65+
```bash
66+
curl -o goroutine.pprof http://localhost:2121/debug/pprof/goroutine
67+
```
68+
69+
### 4. **Execution Trace**
70+
To collect an execution trace:
71+
```bash
72+
curl -o trace.out http://localhost:2121/debug/pprof/trace
73+
```
74+
75+
---
76+
77+
## Analyzing Profiling Data
78+
79+
### 1. Using go tool pprof
80+
To analyze CPU, memory, or goroutine profiles:
81+
```bash
82+
go tool pprof <profile_file>
83+
```
84+
85+
#### **`top`**
86+
Shows the functions consuming the most resources (e.g., CPU or memory).
87+
```bash
88+
go tool pprof cpu.pprof
89+
(pprof) top
90+
```
91+
92+
#### **`list`**
93+
Displays the source code of a specific function, along with resource usage.
94+
```bash
95+
(pprof) list <function_name>
96+
```
97+
Example:
98+
```bash
99+
(pprof) list main.myFunction
100+
```
101+
102+
#### **`web`**
103+
Generates a visual representation of the profile in your browser. This requires Graphviz to be installed.
104+
```bash
105+
(pprof) web
106+
```
107+
108+
109+
### 2. Using go tool trace
110+
To analyze execution traces:
111+
```bash
112+
go tool trace trace.out
113+
```
114+
115+
---
116+
117+
## Example Workflow
118+
119+
1. **Set Environment Variables**:
120+
```bash
121+
METRICS_PORT=2121
122+
```
123+
124+
2. **Run Your GoFr Application**:
125+
```bash
126+
go run main.go
127+
```
128+
129+
3. **Collect Profiling Data**:
130+
- Collect a CPU profile:
131+
```bash
132+
curl -o cpu.pprof http://localhost:2121/debug/pprof/profile
133+
```
134+
- Collect a memory profile:
135+
```bash
136+
curl -o mem.pprof http://localhost:2121/debug/pprof/heap
137+
```
138+
139+
140+
4. **Analyze the Data**:
141+
- Analyze the CPU profile:
142+
```bash
143+
go tool pprof cpu.pprof
144+
(pprof) top
145+
(pprof) list main.myFunction
146+
(pprof) web
147+
```
148+
- Analyze the memory profile:
149+
```bash
150+
go tool pprof mem.pprof
151+
(pprof) top
152+
(pprof) list main.myFunction
153+
(pprof) web
154+
```
155+
156+
---
157+
158+
## References
159+
- [Go `pprof` Documentation](https://pkg.go.dev/net/http/pprof)
160+
- [Profiling Go Programs](https://blog.golang.org/profiling-go-programs)
161+
- [Go Execution Tracer](https://golang.org/doc/diagnostics.html#tracing)

Diff for: ‎docs/advanced-guide/http-authentication/page.md

+60-3
Original file line numberDiff line numberDiff line change
@@ -138,15 +138,72 @@ It involves sending the prefix `Bearer` trailed by the encoded token within the
138138
GoFr supports authenticating tokens encoded by algorithm `RS256/384/512`.
139139

140140
### App level Authentication
141-
Enable OAuth 2.0 with three-legged flow to authenticate requests
141+
Enable OAuth 2.0 with three-legged flow to authenticate requests. Use `EnableOAuth(jwks-endpoint,refresh_interval, options ...jwt.ParserOption)` to configure GoFr with pre-defined credentials.
142142

143-
Use `EnableOAuth(jwks-endpoint,refresh_interval)` to configure GoFr with pre-defined credentials.
143+
### Description
144+
`EnableOAuth` configures OAuth authentication middleware for the application.
145+
146+
- It registers a new HTTP service to fetch **JSON Web Key Sets (JWKS)**, which are used to verify JWTs.
147+
- The JWKS endpoint is periodically refreshed based on the specified refresh interval.
148+
- Additional JWT validation options can be passed using `jwt.ParserOption`, allowing fine-grained control over claim validation.
149+
150+
### Parameters
151+
| Parameter | Type | Description |
152+
|------------------|-------------------|-------------|
153+
| `jwksEndpoint` | `string` | URL of the JWKS endpoint used to retrieve signing keys for token verification. |
154+
| `refreshInterval` | `int` | Interval (in seconds) at which the JWKS cache is refreshed. |
155+
| `options` | `...jwt.ParserOption` | Optional JWT claim validation configurations, such as issuer, audience, and expiration requirements. |
156+
157+
### Available JWT Claim Validations
158+
159+
#### Expiration (`exp`) Validation
160+
If the `exp` claim is present, it is always validated to ensure the token has not expired. However, to make the `exp` claim mandatory in our JWT tokens, we can use:
161+
162+
```go
163+
jwt.WithExpirationRequired()
164+
```
165+
> This ensures that every token must include the `exp` claim, making expiration validation a strict requirement.
166+
167+
#### Issued At (`iat`) Validation
168+
If the `iat` claim is present, it is ensured that tokens are not accepted before their issuance time. No additional configuration is needed for this validation.
169+
170+
#### Not Before (`nbf`) Validation
171+
If the `nbf` claim is present, it is always validated to ensure that a JWT is only valid after a certain time. No additional configuration is needed for this validation.
172+
173+
#### Audience (`aud`) Validation
174+
Verifies that the token is intended for the expected audience.
175+
176+
```go
177+
jwt.WithAudience("https://api.example.com")
178+
```
179+
180+
#### Subject (`sub`) Validation
181+
Ensures the token is associated with the expected subject.
182+
183+
```go
184+
jwt.WithSubject("[email protected]")
185+
```
186+
187+
#### Issuer (`iss`) Validation
188+
Ensures the token is issued by a trusted authority.
189+
190+
```go
191+
jwt.WithIssuer("https://auth.example.com")
192+
```
193+
194+
### Example
144195

145196
```go
146197
func main() {
147198
app := gofr.New()
148199

149-
app.EnableOAuth("http://jwks-endpoint", 20)
200+
app.EnableOAuth(
201+
"http://jwks-endpoint",
202+
20,
203+
jwt.WithExpirationRequired(), // to enforce presence of exp claim in every token
204+
jwt.WithAudience("https://api.example.com"),
205+
jwt.WithIssuer("https://auth.example.com")
206+
)
150207

151208
app.GET("/protected-resource", func(c *gofr.Context) (interface{}, error) {
152209
// Handle protected resource access

Diff for: ‎docs/datasources/getting-started/page.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -148,9 +148,9 @@ as unnecessary database drivers are not being compiled and added to the build.
148148
- SurrealDB
149149
- ✅
150150
- ✅
151-
-
152151
- ✅
153-
-
152+
- ✅
153+
- ✅
154154
---
155155

156156

Diff for: ‎docs/navigation.js

+17-12
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ export const navigation = [
4545
{
4646
title: 'Overriding Default',
4747
href: '/docs/advanced-guide/overriding-default',
48-
desc: "Understand how to override default configurations and behaviors in GoFR to tailor framework to your specific needs."
48+
desc: "Understand how to override default configurations and behaviors in GoFr to tailor framework to your specific needs."
4949
},
5050
{
5151
title: 'Remote Log Level Change',
@@ -70,12 +70,12 @@ export const navigation = [
7070
{
7171
title: 'Adding Custom Middleware',
7272
href: '/docs/advanced-guide/middlewares',
73-
desc: "Learn how to add custom middleware to your GoFR application for enhanced functionality and request processing."
73+
desc: "Learn how to add custom middleware to your GoFr application for enhanced functionality and request processing."
7474
},
7575
{
7676
title: 'HTTP Communication',
7777
href: '/docs/advanced-guide/http-communication',
78-
desc: "Get familiar with making HTTP requests and handling responses within your GoFR application to facilitate seamless communication."
78+
desc: "Get familiar with making HTTP requests and handling responses within your GoFr application to facilitate seamless communication."
7979
},
8080
{
8181
title: 'HTTP Authentication',
@@ -95,52 +95,57 @@ export const navigation = [
9595
{
9696
title: 'Handling Data Migrations',
9797
href: '/docs/advanced-guide/handling-data-migrations',
98-
desc: "Explore strategies for managing data migrations within your GoFR application to ensure smooth transitions and data integrity."
98+
desc: "Explore strategies for managing data migrations within your GoFr application to ensure smooth transitions and data integrity."
9999
},
100100
{
101101
title: 'Writing gRPC Server/Client',
102102
href: '/docs/advanced-guide/grpc',
103-
desc: "Step-by-step guide on writing a gRPC server in GoFR to facilitate efficient communication between services."
103+
desc: "Step-by-step guide on writing a gRPC server in GoFr to facilitate efficient communication between services."
104104
},
105105
{
106106
title: 'Using Pub/Sub',
107107
href: '/docs/advanced-guide/using-publisher-subscriber',
108-
desc: "Discover how to gofr seamlessly allows to integrate different Pub/Sub systems in your application for effective messaging and event-driven architectures."
108+
desc: "Discover how to GoFr seamlessly allows to integrate different Pub/Sub systems in your application for effective messaging and event-driven architectures."
109109
},
110110
{
111111
title: 'Key Value Store',
112112
href: '/docs/advanced-guide/key-value-store',
113-
desc: "Explore how to implement and manage a key-value store in your GoFR application for fast and efficient data retrieval."
113+
desc: "Explore how to implement and manage a key-value store in your GoFr application for fast and efficient data retrieval."
114114
},
115115
{
116116
title: 'Dealing with SQL',
117117
href: '/docs/advanced-guide/dealing-with-sql',
118-
desc: "Get insights into best practices for working with SQL databases in GoFR, including query optimization and error handling."
118+
desc: "Get insights into best practices for working with SQL databases in GoFr, including query optimization and error handling."
119119
},
120120
{
121121
title: 'Automatic SwaggerUI Rendering',
122122
href: '/docs/advanced-guide/swagger-documentation',
123-
desc: "Learn how to automatically render SwaggerUI documentation for your GoFR APIs, improving discoverability and usability."
123+
desc: "Learn how to automatically render SwaggerUI documentation for your GoFr APIs, improving discoverability and usability."
124124
},
125125
{
126126
title: 'Error Handling',
127127
href: '/docs/advanced-guide/gofr-errors',
128-
desc: "Understand error handling mechanisms in GoFR to ensure robust applications and improved user experience."
128+
desc: "Understand error handling mechanisms in GoFr to ensure robust applications and improved user experience."
129129
},
130130
{
131131
title: 'Handling File',
132132
href: '/docs/advanced-guide/handling-file',
133-
desc: "Explore how GoFR enables efficient file handling by abstracting remote and local filestore providers in your Go application. Learn to manage file uploads, downloads, and storage seamlessly, enhancing your application's capability to work with diverse data sources."
133+
desc: "Explore how GoFr enables efficient file handling by abstracting remote and local filestore providers in your Go application. Learn to manage file uploads, downloads, and storage seamlessly, enhancing your application's capability to work with diverse data sources."
134134
},
135135
{
136136
title: 'WebSockets',
137137
href: '/docs/advanced-guide/websocket',
138-
desc: "Explore how gofr eases the process of WebSocket communication in your Golang application for real-time data exchange."
138+
desc: "Explore how GoFr eases the process of WebSocket communication in your Golang application for real-time data exchange."
139139
},
140140
{
141141
title: 'Serving-Static Files',
142142
href: '/docs/advanced-guide/serving-static-files',
143143
desc: "Know how GoFr automatically serves static content from a static folder in the application directory."
144+
},
145+
{
146+
title: 'Profiling in GoFr Applications',
147+
href: '/docs/advanced-guide/debugging',
148+
desc: "Discover GoFr auto-enables pprof profiling by leveraging its built-in configurations."
144149
}
145150
],
146151
},

0 commit comments

Comments
 (0)