Merge branch '2201.10.x' into u10-libs-version

examples/graphql-client-security-jwt-authentication/graphql_client_security_jwt_authentication.md

@@ -2,14 +2,14 @@
 
 The `graphql:Client` can connect to a service that is secured with self-signed JWT by adding the `Authorization: Bearer <token>` header by passing the `graphql:JwtIssuerConfig` to the `auth` configuration of the client. A self-signed JWT is issued before the request is sent.
 
-::: code graphql_client_security_self_signed_jwt_authentication.bal :::
+::: code graphql_client_security_jwt_authentication.bal :::
 
 ## Prerequisites
 - Run the GraphQL service given in the [JWT Auth service](/learn/by-example/graphql-service-jwt-auth/) example.
 
 Run the client program by executing the command below.
 
-::: out graphql_client_security_self_signed_jwt_authentication.out :::
+::: out graphql_client_security_jwt_authentication.out :::
 
 ## Related links
 - [`graphql:JwtIssuerConfig` record - API documentation](https://lib.ballerina.io/ballerina/graphql/latest#JwtIssuerConfig)

examples/http-access-logs/Config.toml

@@ -1,5 +1,9 @@
 [ballerina.http.accessLogConfig]
 # Enable printing access logs on the Console. The default value is `false`.
 console = true
+# Specify the format of access logs. Options are `flat` or `json`. The default value is `flat`.
+format = "flat"
+# List of attributes to include in the access logs. This field is optional.
+attributes = ["ip", "date_time", "request", "status", "response_body_size", "http_referrer", "http_user_agent"]
 # Specify the file path to save the access logs. This is optional.  
 path = "testAccessLog.txt"

examples/http-access-logs/http_access_logs.bal

@@ -1,6 +1,6 @@
 import ballerina/http;
 
-type Album readonly & record {|
+public type Album readonly & record {|
     string title;
     string artist;
 |};

examples/http-access-logs/http_access_logs.md

@@ -1,6 +1,6 @@
 # HTTP service - Access logs
 
-Ballerina allows enabling HTTP access logs, which can be used to record the HTTP requests handled by the application. HTTP access logs are disabled by default. Set `console=true` under `ballerina.http.accessLogConfig` in the `Config.toml` file to enable them. Additionally, the `path` field can be used to specify the file path to save the access logs.
+Ballerina allows enabling HTTP access logs, which can be used to record the HTTP requests handled by the application. HTTP access logs are disabled by default. Set `console=true` under `ballerina.http.accessLogConfig` in the `Config.toml` file to enable them. Additionally, the `path` field can be used to specify the file path to save the access logs. The log format can be specified as either `flat` or `json` using the optional `format` field (defaults to `flat`). Furthermore, you can customize the logged attributes using the optional `attributes` field.
 
 ::: code http_access_logs.bal :::
 

examples/http-access-logs/http_access_logs.server.out

@@ -1,3 +1,3 @@
 $ bal run http_access_logs.bal
 ballerina: HTTP access log enabled
-127.0.0.1 - - [15/Dec/2022:11:39:42 +0530] "GET /albums HTTP/1.1" 200 95 "-" "curl/7.79.1" 
+127.0.0.1 [11/Jul/2024:13:21:01.620 +0530] "GET /albums HTTP/1.1" 200 95 "-" "curl/8.4.0"

examples/http-sse-client/http_sse_client.bal

@@ -0,0 +1,13 @@
+import ballerina/http;
+import ballerina/io;
+
+public function main() returns error? {
+    http:Client clientEp = check new ("localhost:9090");
+    // Make a GET request to the "/stocks" endpoint and receive a stream of `http:SseEvent`.
+    stream<http:SseEvent, error?> eventStream = check clientEp->/stocks;
+    // Iterate over the stream and handle each event.
+    check from http:SseEvent event in eventStream
+        do {
+            io:println("Stock price: ", event.data);
+        };
+}

examples/http-sse-client/http_sse_client.client.out

@@ -0,0 +1,7 @@
+$ bal run http_sse_client.bal
+
+Stock price: 249.9963321685791
+Stock price: 56.58070945739746
+Stock price: 571.2127494812012
+Stock price: 217.98820853233337
+Stock price: 21.891758739948273

examples/http-sse-client/http_sse_client.md

@@ -0,0 +1,16 @@
+# HTTP client - Server-sent events
+
+The HTTP client supports receiving real-time data from services using server-sent events (SSE). It allows payload-binding of a stream of `http:SseEvent` when consuming SSE from a service. This payload binding fails if the content type header is not present in the response or does not have the value `text/event-stream`.
+
+::: code http_sse_client.bal :::
+
+## Prerequisites
+- Run the HTTP service given in the [Server-sent events](/learn/by-example/http-sse-service/) example.
+
+Run the client program by executing the following command.
+
+::: out http_sse_client.client.out :::
+
+## Related links
+- [`http` module - API documentation](https://lib.ballerina.io/ballerina/http/latest/)
+- [Client action return types - Specification](/spec/http/#243-client-action-return-types)

examples/http-sse-client/http_sse_client.metatags

@@ -0,0 +1,2 @@
+description: This example demonstrates how server-sent events (SSE) can be consumed using an HTTP client.
+keywords: ballerina, ballerina by example, bbe, http, SSE, client

examples/http-sse-service/http_sse_service.bal

@@ -0,0 +1,33 @@
+import ballerina/http;
+import ballerina/lang.runtime;
+import ballerina/random;
+
+service /stocks on new http:Listener(9090) {
+    // This resource method returns a stream of `http:SseEvent` (with stock prices)
+    // to push real-time data to clients using server-sent events (SSE).
+    resource function get .() returns stream<http:SseEvent, error?> {
+        // Create a new value of type `StockPriceEventGenerator` to generate stock price events.
+        StockPriceEventGenerator generator = new;
+        // Return a new stream that uses the generator to produce events.
+        return new (generator);
+    }
+}
+
+// Define a stream implementor that can be used to create a stream 
+// of `http:SseEvent`, representing stock price events.
+class StockPriceEventGenerator {
+    int eventCounter = 0;
+
+    public isolated function next() returns record {|http:SseEvent value;|}|error? {
+        // If the eventCounter reaches 5, stop generating events by returning nil.
+        if self.eventCounter == 5 {
+            return ();
+        }
+        self.eventCounter += 1;
+        runtime:sleep(1);
+        // Generate a random stock price
+        float stockPrice = (check random:createIntInRange(1, 1000)) * random:createDecimal();
+        http:SseEvent event = {data: stockPrice.toString()};
+        return {value: event};
+    }
+}

examples/http-sse-service/http_sse_service.client.out

@@ -0,0 +1,27 @@
+$ curl -v localhost:9090/stocks
+*   Trying [::1]:9090...
+* Connected to localhost (::1) port 9090
+> GET /stocks/stockA HTTP/1.1
+> Host: localhost:9090
+> User-Agent: curl/8.4.0
+> Accept: */*
+> 
+< HTTP/1.1 200 OK
+< content-type: text/event-stream
+< cache-control: no-cache,public
+< transfer-encoding: chunked
+< connection: keep-alive
+< server: ballerina
+< date: Fri, 2 Aug 2024 12:02:04 +0530
+< 
+data: 76.6014928817749
+
+data: 789.1765828132629
+
+data: 241.89215344190598
+
+data: 494.8120536804199
+
+data: 234.36854779720306
+
+* Connection #0 to host localhost left intact

examples/http-sse-service/http_sse_service.md

@@ -0,0 +1,17 @@
+# HTTP service - Server-sent events
+
+Ballerina HTTP services support pushing real-time data to clients using server-sent events (SSE). A stream of type `http:SseEvent` can be returned from service resource methods. This feature automatically handles sending SSE and sets the content type to `text/event-stream` and the transfer encoding to chunked.
+
+::: code http_sse_service.bal :::
+
+Run the service program by executing the following command.
+
+::: out http_sse_service.server.out :::
+
+Invoke the service by executing the following cURL command in a new terminal.
+
+::: out http_sse_service.client.out :::
+
+## Related links
+- [`http` module - API documentation](https://lib.ballerina.io/ballerina/http/latest/)
+- [Resource return types - Specification](/spec/http/#235-return-types)

examples/http-sse-service/http_sse_service.metatags

@@ -0,0 +1,2 @@
+description: This example demonstrates how server-sent events (SSE) can be produced using an HTTP service.
+keywords: ballerina, ballerina by example, bbe, http, SSE, service

examples/http-sse-service/http_sse_service.server.out

@@ -0,0 +1 @@
+$ bal run http_sse_service.bal

examples/index.json

@@ -2256,6 +2256,14 @@
         "verifyOutput": false,
         "disablePlayground": false,
         "isLearnByExample": false
+      },
+      {
+        "name": "Server-sent events",
+        "url": "http-sse-service",
+        "verifyBuild": true,
+        "verifyOutput": false,
+        "disablePlayground": false,
+        "isLearnByExample": false
       }
     ]
   },
@@ -2327,6 +2335,14 @@
         "verifyOutput": false,
         "disablePlayground": false,
         "isLearnByExample": false
+      },
+      {
+        "name": "Server-sent events",
+        "url": "http-sse-client",
+        "verifyBuild": true,
+        "verifyOutput": false,
+        "disablePlayground": false,
+        "isLearnByExample": false
       }
     ]
   },