@longtq2501/next-spring-skills 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@longtq2501/next-spring-skills",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Standardized best practices and code patterns for Next.js and Spring Boot",
   "bin": {
     "next-spring-skills": "bin/cli.js"

package/skills/SKILL.md

@@ -63,6 +63,9 @@ See [ui-state.md](./nextjs/ui-state.md) for Zustand store patterns and URL param
 ### Three.js & 3D
 See [threejs.md](./nextjs/threejs.md) for high-performance 3D development and R3F.
 
+### WebRTC & P2P
+See [webrtc.md](./nextjs/webrtc.md) for real-time media and signaling.
+
 ### Accessibility (a11y)
 See [accessibility.md](./nextjs/accessibility.md) for semantic HTML and ARIA.
 
@@ -111,6 +114,10 @@ High-performance, stateless REST API patterns using Spring Boot, JPA, and JWT.
 - [Query Optimization](./spring/query_optimization.md)
 - [Performance Optimization](./spring/performance_optimization.md)
 
+### Real-time
+- [WebSocket & STOMP](./spring/websocket.md)
+- [Server-Sent Events (SSE)](./spring/sse.md)
+
 ---
 
 **Templates:** See the [spring/templates/](./spring/templates/) directory for production-ready boilerplates.

package/skills/nextjs/webrtc.md

@@ -0,0 +1,77 @@
+# Skill: WebRTC - Peer-to-Peer Communication
+
+Guidelines for implementing real-time video, audio, and data streaming between browsers.
+
+## TL;DR - Quick Reference
+
+### Critical Rules
+1. **Signaling Server Required**: WebRTC needs a side-channel (WebSocket/SSE) to exchange SDP and ICE candidates.
+2. **ICE Protocol**: Use STUN/TURN servers to bypass NAT and Firewalls. (Google's STUN is for dev, use Twilio/Metered for Prod).
+3. **Media Constraints**: Use `navigator.mediaDevices.getUserMedia` with specific resolutions to optimize performance.
+4. **DataChannels**: Use `RTCDataChannel` for low-latency P2P data (e.g., file sharing, gaming).
+5. **Security**: Always use HTTPS. WebRTC will not work on non-secure origins.
+
+---
+
+## 1. Core Lifecycle (Signaling)
+
+WebRTC communication happens in steps:
+1. **Offer**: Peer A creates an offer (SDP).
+2. **Answer**: Peer B receives the offer and sends back an answer.
+3. **ICE Candidates**: Both peers exchange network pathway information.
+
+// Bad: Trying to connect without a signaling server
+// Good: Using WebSocket for signaling
+socket.on('offer', async (offer) => {
+  await peerConnection.setRemoteDescription(new RTCSessionDescription(offer));
+  const answer = await peerConnection.createAnswer();
+  await peerConnection.setLocalDescription(answer);
+  socket.emit('answer', answer);
+});
+
+---
+
+## 2. Media Handling
+
+### Capturing Video/Audio
+// Good: Requesting specific constraints
+const stream = await navigator.mediaDevices.getUserMedia({
+  video: { width: 1280, height: 720 },
+  audio: true
+});
+videoRef.current.srcObject = stream;
+
+---
+
+## 3. NAT Traversal (STUN/TURN)
+Without these, peers cannot find each other over the public internet.
+
+// Good: Configuration with ICE servers
+const pcConfig = {
+  iceServers: [
+    { urls: 'stun:stun.l.google.com:19302' }, // STUN finds public IP
+    { 
+      urls: 'turn:my-turn-server.com', // TURN relays data if P2P fails
+      username: 'user', 
+      credential: 'password' 
+    }
+  ]
+};
+const peerConnection = new RTCPeerConnection(pcConfig);
+
+---
+
+## 4. Performance & Troubleshooting
+
+### Optimization
+- **Simulcast**: Send multiple resolution streams to cater to different bandwidths.
+- **Bitrate Capping**: Manually limit bandwidth to prevent congestion.
+
+### Debugging
+- **chrome://webrtc-internals**: Essential tool for inspecting connections and bitrates.
+
+---
+
+## Related Skills
+- **WebSocket & STOMP**: `skills/spring/websocket.md`
+- **Interactivity & Animation**: `skills/nextjs/interactivity.md`

package/skills/spring/sse.md

@@ -0,0 +1,91 @@
+# Skill: Server-Sent Events (SSE)
+
+Guidelines for implementing lightweight unidirectional server-to-client streaming.
+
+## TL;DR - Quick Reference
+
+### Critical Rules
+1. **Unidirectional**: Use SSE for server-to-client push only (e.g., notifications, stock tickers). Use WebSocket for bi-directional.
+2. **Standard Protocol**: SSE uses standard HTTP and doesn't require a special protocol upgrade (unlike WebSocket).
+3. **Reconnection**: Browsers automatically reconnect to SSE streams if the connection drops.
+4. **Content-Type**: Always set response to `text/event-stream`.
+5. **Resource Cleaning**: Always complete or timeout `SseEmitter` to avoid thread/memory leaks.
+
+---
+
+## 1. Spring Boot Implementation
+
+### SseEmitter (Imperative)
+Ideal for basic notifications within a standard Spring Web project.
+
+// Good: Basic SSE Controller
+@GetMapping(path = "/notifications", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
+public SseEmitter streamNotifications() {
+    SseEmitter emitter = new SseEmitter(30_000L); // 30s timeout
+    
+    // In a real app, store emitter in a Map keyed by UserID
+    executor.execute(() -> {
+        try {
+            emitter.send(SseEmitter.event()
+                .name("message")
+                .data("Hello at " + LocalTime.now()));
+            emitter.complete();
+        } catch (Exception e) {
+            emitter.completeWithError(e);
+        }
+    });
+    return emitter;
+}
+
+### WebFlux (Reactive)
+Best for high-concurrency streaming.
+
+// Good: Reactive Streaming
+@GetMapping(path = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
+public Flux<String> streamFlux() {
+    return Flux.interval(Duration.ofSeconds(1))
+               .map(i -> "Data chunk " + i);
+}
+
+---
+
+## 2. Next.js Client Integration
+
+### EventSource API
+SSE is natively supported by the browser's `EventSource`.
+
+// Good: Consuming SSE in React
+useEffect(() => {
+  const eventSource = new EventSource('/api/notifications');
+  
+  eventSource.onmessage = (event) => {
+    const newData = JSON.parse(event.data);
+    setNotifications(prev => [...prev, newData]);
+  };
+
+  eventSource.onerror = (err) => {
+    console.error("SSE failed:", err);
+    eventSource.close();
+  };
+
+  return () => eventSource.close(); // Important: Cleanup
+}, []);
+
+---
+
+## 3. Advanced Patterns
+
+### Last-Event-ID
+Used for data consistency during reconnections.
+- The server sends an `id` with each event.
+- If the client reconnects, it sends the `Last-Event-ID` header.
+
+### Scaling SSE
+- **Load Balancers**: Ensure your load balancer supports long-lived connections and `text/event-stream` (disable buffering).
+- **Redis Pub/Sub**: Use Redis to broadcast events across multiple server instances.
+
+---
+
+## Related Skills
+- **WebSocket & STOMP**: `skills/spring/websocket.md`
+- **Performance Optimization**: `skills/spring/performance_optimization.md`

package/skills/spring/templates/WebSocketConfig.java

@@ -0,0 +1,42 @@
+package com.example.config;
+
+import org.springframework.context.annotation.Configuration;
+import org.springframework.messaging.simp.config.ChannelRegistration;
+import org.springframework.messaging.simp.config.MessageBrokerRegistry;
+import org.springframework.web.socket.config.annotation.EnableWebSocketMessageBroker;
+import org.springframework.web.socket.config.annotation.StompEndpointRegistry;
+import org.springframework.web.socket.config.annotation.WebSocketMessageBrokerConfigurer;
+
+/**
+ * Standard WebSocket Configuration using STOMP.
+ */
+@Configuration
+@EnableWebSocketMessageBroker
+public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {
+
+    @Override
+    public void configureMessageBroker(MessageBrokerRegistry config) {
+        // /topic for Broadcast (1-to-many)
+        // /queue for Private (1-to-1)
+        config.enableSimpleBroker("/topic", "/queue");
+
+        // Prefix for messages originating from the client
+        config.setApplicationDestinationPrefixes("/app");
+
+        // Prefix for private messages (SendToUser)
+        config.setUserDestinationPrefix("/user");
+    }
+
+    @Override
+    public void registerStompEndpoints(StompEndpointRegistry registry) {
+        registry.addEndpoint("/ws")
+                .setAllowedOrigins("*") // In production, limit this to your frontend domain
+                .withSockJS(); // Enables fallback options for older browsers
+    }
+
+    @Override
+    public void configureClientInboundChannel(ChannelRegistration registration) {
+        // Add interceptors for security (e.g., JWT validation on CONNECT frames)
+        // registration.interceptors(myAuthInterceptor);
+    }
+}

package/skills/spring/websocket.md

@@ -0,0 +1,108 @@
+# Skill: WebSocket & Real-time Communication
+
+Guidelines for implementing robust, secure, and scalable real-time messaging using Spring Boot (STOMP) and Next.js.
+
+## TL;DR - Quick Reference
+
+### Critical Rules
+1. **Use STOMP over WebSocket**: Standard sub-protocol for messaging with built-in routing (`@MessageMapping`).
+2. **Security first**: Authenticate the initial WebSocket handshake using JWT in headers or query params.
+3. **Heartbeats**: Enable heartbeats to detect and close dead connections promptly.
+4. **Error Handling**: Use `@MessageExceptionHandler` to gracefully handle errors in message processing.
+5. **Payload Size**: Keep WebSocket messages small; for large data, send a notification and fetch via REST.
+
+---
+
+## 1. Spring Boot Configuration
+
+### STOMP Setup
+Always separate the message broker into a "Simple Broker" (for dev/local) and a "Full Broker" (like RabbitMQ) for production scaling.
+
+// Good: Basic STOMP Configuration
+@Configuration
+@EnableWebSocketMessageBroker
+public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {
+    @Override
+    public void configureMessageBroker(MessageBrokerRegistry config) {
+        config.enableSimpleBroker("/topic", "/queue"); // Simple in-memory broker
+        config.setApplicationDestinationPrefixes("/app");
+    }
+
+    @Override
+    public void registerStompEndpoints(StompEndpointRegistry registry) {
+        registry.addEndpoint("/ws")
+                .setAllowedOrigins("*")
+                .withSockJS(); // Fallback for browsers without WS support
+    }
+}
+
+---
+
+## 2. Message Handling
+
+### Controller Pattern
+Use `@MessageMapping` to handle incoming messages and `@SendTo` to broadcast output.
+
+// Good: Real-time Chat Example
+@Controller
+public class ChatController {
+    
+    @MessageMapping("/chat.send")
+    @SendTo("/topic/public")
+    public ChatMessage sendMessage(@Payload ChatMessage message) {
+        return message;
+    }
+
+    @MessageExceptionHandler
+    @SendToUser("/queue/errors")
+    public String handleException(Exception exception) {
+        return "Error: " + exception.getMessage();
+    }
+}
+
+---
+
+## 3. Security (JWT & Interceptors)
+Since WebSockets are long-lived, the initial handshake is the critical entry point, but STOMP frames also need individual validation.
+
+### Handshake vs. Interceptors
+- **Handshake Interceptor**: Used for the initial HTTP upgrade request.
+- **Channel Interceptor**: Required for validating tokens on every `CONNECT` or `SUBSCRIBE` frame.
+
+// Good: Registering a STOMP Interceptor
+@Override
+public void configureClientInboundChannel(ChannelRegistration registration) {
+    registration.interceptors(new ChannelInterceptor() {
+        @Override
+        public Message<?> preSend(Message<?> message, MessageChannel channel) {
+            StompHeaderAccessor accessor = MessageHeaderUtils.getAccessor(message, StompHeaderAccessor.class);
+            if (StompCommand.CONNECT.equals(accessor.getCommand())) {
+                String token = accessor.getFirstNativeHeader("Authorization");
+                // Validate token and set SecurityContext
+            }
+            return message;
+        }
+    });
+}
+
+---
+
+## 4. Frontend Integration (Next.js)
+Use libraries like `@stomp/stompjs` for robust STOMP client management.
+
+// Good: Client-side Connection
+const client = new Client({
+  brokerURL: 'ws://localhost:8080/ws',
+  onConnect: () => {
+    client.subscribe('/topic/public', (message) => {
+      console.log('Received:', JSON.parse(message.body));
+    });
+  },
+});
+client.activate();
+
+---
+
+## Related Skills
+- **Security Config**: `skills/spring/security_config.md`
+- **Performance Optimization**: `skills/spring/performance_optimization.md`