Skip to content

Commit ef8ca1b

Browse files
blessingernest54blessingernest54
authored
Merge branch 'main' into feature/student-progress-insights
2 parents 4ba784e + ea5878e commit ef8ca1b

62 files changed

Lines changed: 5146 additions & 91 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.git_commit_msg3.txt‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
feat(api): user-specific rate limiting and CDN static asset delivery
2+
3+
Implements per-user graduated rate limiting with burst handling and
4+
a CDN layer for static asset delivery with cache invalidation support.
5+
6+
User-specific rate limiting:
7+
- Four tiers: free (30rpm/10burst), pro (120/30), enterprise (600/100), internal (6000/500)
8+
- Token-bucket algorithm via rate-limiter-flexible (main window + burst window)
9+
- Unauthenticated requests fall back to existing IP-based limiter
10+
- Clear limit headers on every response: X-RateLimit-Tier/Limit/Remaining/Reset/Burst-Limit
11+
- 429 responses include tier info, retry-after, and upgrade URL
12+
- GET /api/v1/rate-limit/status — live usage status for authenticated user
13+
- GET /api/v1/rate-limit/tiers — public tier definitions
14+
- Prometheus metrics: hit counters, consumed ratio histogram, burst usage counter
15+
- All limits configurable via environment variables
16+
17+
CDN static asset delivery:
18+
- ETag generation and conditional 304 responses on all GET endpoints
19+
- Cache-Control strategy by asset type (static=immutable 1yr, api-docs=1h, api-response=30s CDN + SWR, dynamic=no-store)
20+
- Cache invalidation via HMAC-SHA256 signed webhook (POST /api/v1/cdn/invalidate)
21+
- GET /api/v1/cdn/status — CDN config and active invalidation store
22+
- CloudFront distribution config (api/cdn/cloudfront-config.json)
23+
- Cloudflare cache rules (api/cdn/cloudflare-cache-rules.json)
24+
- Prometheus metrics: cache hits/misses, invalidations, asset serve time
25+
26+
Closes #470
27+
Closes #473

‎.github/workflows/ci.yml‎

Lines changed: 39 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -124,10 +124,45 @@ jobs:
124124
name: perf-report
125125
path: target/perf_report.json
126126

127+
visual-regression:
128+
name: Visual Regression
129+
runs-on: ubuntu-latest
130+
timeout-minutes: 10
131+
steps:
132+
- uses: actions/checkout@v4
133+
134+
- name: Setup Node.js
135+
uses: actions/setup-node@v4
136+
with:
137+
node-version: "20"
138+
cache: "npm"
139+
140+
- name: Install dependencies
141+
run: npm ci
142+
143+
- name: Install Playwright browsers
144+
run: npx playwright install --with-deps
145+
146+
- name: Generate visual baselines in CI
147+
run: npm run visual:test:update
148+
149+
- name: Run visual regression tests
150+
run: npm run visual:test
151+
152+
- name: Upload visual diff report
153+
if: always()
154+
uses: actions/upload-artifact@v4
155+
with:
156+
name: visual-regression-report
157+
path: |
158+
visual-tests/playwright-report
159+
visual-tests/test-results
160+
visual-tests/tests/__screenshots__
161+
127162
ci-success:
128163
name: CI Success
129164
runs-on: ubuntu-latest
130-
needs: [format, clippy, build, test, performance]
165+
needs: [format, clippy, build, test, performance, visual-regression]
131166
if: always()
132167
steps:
133168
- name: Check all jobs
@@ -136,13 +171,15 @@ jobs:
136171
"${{ needs.clippy.result }}" != "success" || \
137172
"${{ needs.build.result }}" != "success" || \
138173
"${{ needs.test.result }}" != "success" || \
139-
"${{ needs.performance.result }}" != "success" ]]; then
174+
"${{ needs.performance.result }}" != "success" || \
175+
"${{ needs.visual-regression.result }}" != "success" ]]; then
140176
echo "One or more CI jobs failed"
141177
echo "Format: ${{ needs.format.result }}"
142178
echo "Clippy: ${{ needs.clippy.result }}"
143179
echo "Build: ${{ needs.build.result }}"
144180
echo "Test: ${{ needs.test.result }}"
145181
echo "Performance: ${{ needs.performance.result }}"
182+
echo "Visual Regression: ${{ needs.visual-regression.result }}"
146183
exit 1
147184
fi
148185
echo "✅ All CI jobs passed successfully"

‎401_CORS_Bug_Analysis.md‎

Lines changed: 256 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,256 @@
1+
# #401 Bug: CORS Issues with External Academic Verification Services
2+
3+
## Issue Overview
4+
5+
**Repository:** StarkMindsHQ/StrellerMinds-SmartContracts
6+
**Issue ID:** #401
7+
**Severity:** Medium
8+
**Category:** Cross-Origin Resource Sharing (CORS) Configuration
9+
10+
## Problem Description
11+
12+
Cross-origin requests to external academic verification services fail intermittently, causing inconsistent behavior in the smart contract's external verification functionality.
13+
14+
## Current Behavior
15+
16+
- ❌ Cross-origin requests to verifiers fail intermittently
17+
- ❌ CORS errors appear occasionally during external verification attempts
18+
- ❌ Retry attempts sometimes succeed, indicating non-deterministic behavior
19+
- ❌ CORS headers are sometimes missing from responses
20+
21+
## Expected Behavior
22+
23+
- ✅ CORS headers should be consistently set correctly for all external verification requests
24+
- ✅ All cross-origin requests should succeed without intermittent failures
25+
- ✅ No retries should be required due to CORS issues
26+
- ✅ Reliable and predictable external verification service integration
27+
28+
## Steps to Reproduce
29+
30+
1. Navigate to the smart contract application
31+
2. Initiate an external academic verification request
32+
3. Observe intermittent CORS errors in the browser console
33+
4. Retry the verification attempt
34+
5. Note that the retry may succeed, indicating non-deterministic behavior
35+
36+
## Root Cause Analysis
37+
38+
### Potential Causes
39+
40+
1. **Inconsistent CORS Configuration**
41+
- CORS middleware may not be properly configured for all endpoints
42+
- Missing pre-flight handling for OPTIONS requests
43+
- Inconsistent header injection across different request types
44+
45+
2. **Race Conditions in Header Setting**
46+
- Asynchronous request handling may cause headers to be set inconsistently
47+
- Multiple middleware components may interfere with CORS header injection
48+
- Timing issues in response processing
49+
50+
3. **Environment-Specific Configuration**
51+
- Different CORS settings between development, staging, and production
52+
- Missing environment variables for CORS configuration
53+
- Inconsistent deployment configurations
54+
55+
4. **Third-Party Service Integration**
56+
- External verification services may have varying CORS policies
57+
- Inconsistent handling of responses from different verification providers
58+
- Missing proper proxy configuration for external service calls
59+
60+
## Technical Investigation Areas
61+
62+
### 1. CORS Middleware Configuration
63+
```javascript
64+
// Check for proper CORS setup
65+
app.use(cors({
66+
origin: ['https://strellerminds.com', 'https://verifier.academic.edu'],
67+
credentials: true,
68+
methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
69+
allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With']
70+
}));
71+
```
72+
73+
### 2. Pre-flight Request Handling
74+
```javascript
75+
// Ensure OPTIONS requests are properly handled
76+
app.options('*', cors());
77+
```
78+
79+
### 3. External Service Proxy Configuration
80+
```javascript
81+
// Verify proxy settings for external verification services
82+
const proxyOptions = {
83+
target: 'https://external-verifier.com',
84+
changeOrigin: true,
85+
secure: true,
86+
headers: {
87+
'Access-Control-Allow-Origin': '*',
88+
'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS'
89+
}
90+
};
91+
```
92+
93+
## Recommended Solutions
94+
95+
### Immediate Fixes (High Priority)
96+
97+
1. **Standardize CORS Configuration**
98+
- Implement consistent CORS middleware across all application routes
99+
- Ensure pre-flight requests are properly handled
100+
- Add comprehensive error logging for CORS-related issues
101+
102+
2. **Add Request/Response Logging**
103+
- Implement detailed logging for all external verification requests
104+
- Log CORS headers in both requests and responses
105+
- Monitor for patterns in intermittent failures
106+
107+
3. **Environment Configuration Review**
108+
- Audit CORS settings across all environments
109+
- Standardize configuration files and environment variables
110+
- Implement configuration validation at startup
111+
112+
### Medium-Term Improvements
113+
114+
1. **Implement Circuit Breaker Pattern**
115+
- Add retry logic with exponential backoff for failed requests
116+
- Implement circuit breaker to prevent cascading failures
117+
- Add health checks for external verification services
118+
119+
2. **Enhanced Error Handling**
120+
- Provide specific error messages for CORS failures
121+
- Implement graceful degradation for external service failures
122+
- Add user-friendly error reporting
123+
124+
3. **Testing and Monitoring**
125+
- Add automated tests for CORS configuration
126+
- Implement monitoring for CORS-related errors
127+
- Set up alerts for intermittent failures
128+
129+
### Long-Term Architecture Changes
130+
131+
1. **API Gateway Implementation**
132+
- Consider implementing an API gateway for consistent CORS handling
133+
- Centralize external service integration through gateway
134+
- Implement rate limiting and request validation
135+
136+
2. **Service Mesh Integration**
137+
- Explore service mesh solutions for better inter-service communication
138+
- Implement consistent observability across all services
139+
- Add distributed tracing for request flow analysis
140+
141+
## Implementation Plan
142+
143+
### Phase 1: Immediate Stabilization (Week 1)
144+
- [ ] Audit current CORS configuration
145+
- [ ] Implement consistent CORS middleware
146+
- [ ] Add comprehensive logging
147+
- [ ] Deploy hotfix to production
148+
149+
### Phase 2: Enhanced Reliability (Week 2-3)
150+
- [ ] Implement retry logic with circuit breaker
151+
- [ ] Add automated testing for CORS scenarios
152+
- [ ] Set up monitoring and alerting
153+
- [ ] Document troubleshooting procedures
154+
155+
### Phase 3: Architecture Improvements (Week 4-6)
156+
- [ ] Design API gateway solution
157+
- [ ] Implement service mesh if needed
158+
- [ ] Performance testing and optimization
159+
- [ ] Full deployment and validation
160+
161+
## Testing Strategy
162+
163+
### Unit Tests
164+
- CORS middleware configuration validation
165+
- Request/response header verification
166+
- Error handling scenarios
167+
168+
### Integration Tests
169+
- End-to-end external verification flows
170+
- Cross-origin request scenarios
171+
- Multi-environment configuration testing
172+
173+
### Load Testing
174+
- High-volume request scenarios
175+
- Concurrent request handling
176+
- Performance under stress
177+
178+
## Monitoring and Alerting
179+
180+
### Key Metrics to Track
181+
- CORS error rate by endpoint
182+
- External verification success rate
183+
- Response time percentiles
184+
- Request retry frequency
185+
186+
### Alert Thresholds
187+
- CORS error rate > 1%
188+
- External verification failure rate > 5%
189+
- Response time > 5 seconds
190+
- Consecutive failures > 3
191+
192+
## Rollback Plan
193+
194+
### Immediate Rollback Triggers
195+
- CORS error rate increase > 10%
196+
- External verification complete failure
197+
- Response time degradation > 50%
198+
- User-reported issues spike
199+
200+
### Rollback Procedure
201+
1. Revert CORS configuration changes
202+
2. Restore previous middleware setup
203+
3. Validate system stability
204+
4. Communicate with stakeholders
205+
206+
## Security Considerations
207+
208+
### CORS Security Best Practices
209+
- Limit allowed origins to specific domains
210+
- Avoid wildcard origins in production
211+
- Implement proper credential handling
212+
- Regular security audits of CORS configuration
213+
214+
### External Service Security
215+
- Validate all external service responses
216+
- Implement request rate limiting
217+
- Add input sanitization for external data
218+
- Monitor for suspicious activity patterns
219+
220+
## Documentation Updates
221+
222+
### Technical Documentation
223+
- Update API documentation with CORS requirements
224+
- Document external service integration patterns
225+
- Create troubleshooting guide for CORS issues
226+
- Update deployment procedures
227+
228+
### User Documentation
229+
- Add error handling information for users
230+
- Document expected behavior during verification
231+
- Provide support contact information
232+
- Create FAQ for common issues
233+
234+
## Success Criteria
235+
236+
### Technical Metrics
237+
- CORS error rate < 0.1%
238+
- External verification success rate > 99.5%
239+
- Response time < 2 seconds (95th percentile)
240+
- Zero intermittent failures over 30-day period
241+
242+
### User Experience Metrics
243+
- No user-reported CORS issues
244+
- Smooth verification process flow
245+
- Consistent behavior across all environments
246+
- Positive user feedback on reliability
247+
248+
## Conclusion
249+
250+
This CORS issue requires immediate attention to ensure reliable external academic verification functionality. The recommended solutions address both immediate stabilization and long-term architectural improvements. Implementation should follow the phased approach to minimize disruption while ensuring comprehensive resolution of the intermittent CORS failures.
251+
252+
**Next Steps:**
253+
1. Assign development team to Phase 1 implementation
254+
2. Set up monitoring for current CORS error rates
255+
3. Begin audit of existing CORS configuration
256+
4. Schedule stakeholder review of proposed solutions

‎Cargo.lock‎

Lines changed: 0 additions & 11 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎api/.env.example‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,5 +17,23 @@ RATE_LIMIT_WINDOW_MS=60000
1717
RATE_LIMIT_MAX_REQUESTS=60
1818
RATE_LIMIT_VERIFY_MAX=100
1919

20+
# Per-user tier limits (requests per minute / burst per 10s)
21+
RATE_LIMIT_FREE_RPM=30
22+
RATE_LIMIT_FREE_BURST=10
23+
RATE_LIMIT_PRO_RPM=120
24+
RATE_LIMIT_PRO_BURST=30
25+
RATE_LIMIT_ENT_RPM=600
26+
RATE_LIMIT_ENT_BURST=100
27+
RATE_LIMIT_INTERNAL_RPM=6000
28+
RATE_LIMIT_INTERNAL_BURST=500
29+
30+
# CDN
31+
CDN_ORIGIN=https://dXXXXXXXXXXXX.cloudfront.net
32+
CDN_MAX_AGE=31536000
33+
CDN_S_MAX_AGE=86400
34+
CDN_SWR=3600
35+
CDN_INVALIDATION_SECRET=change-me-in-production
36+
CLOUDFRONT_DISTRIBUTION_ID=EXXXXXXXXXXXX
37+
2038
# CORS
2139
CORS_ORIGINS=http://localhost:3000,https://app.strellerminds.com

0 commit comments

Comments
 (0)