[Community Call] Ballerina Swan Lake HTTP Module Changes

Community Call - July 2021
Changes to the HTTP Package in
Ballerina Swan Lake

Agenda
- Getting involved and showing your support
- https://github.com/ballerina-platform/community
- Changes to the HTTP package in Swan Lake
- Changes to service and client implementations - Chamil Elladeniya
- Security changes - Chanaka Lakmal
- QnA

Changes to HTTP Package in Swan Lake
July 2021

Outline
➔ Service,
◆ Declaration, Absolute resource path
➔ Resource
◆ Accessor, Name, Path param, Rest param
◆ Signature params such as query, payload, header, caller and
request
◆ Return types
➔ Client
◆ Response payload retrieval
◆ Headers, Media type arguments in client operation
➔ Security

Service declaration
A syntactic sugar for creating services.
Gets desugared into creating a listener object, creating a service object,
attaching the service object to the listener object, etc,.
service-declaration := "service" [[type-descriptor] variable-name] "on" expression-list etc
service http:Service /basePath on new http:Listener(9090) {
resource function get foo() returns string {
return "hello world";
}
}

Service class declaration
service isolated class SClass {
*http:Service;
isolated resource function get greeting() returns string {
}
}
listener http:Listener serviceListener = new (9090);
http:Service httpService = new SClass();
public function main() {
error? err1 = serviceListener.attach(httpService, ["foo", "bar"]);
error? err2 = serviceListener.start();
runtime:registerListener(serviceListener);
}

Service constructor expression
listener http:Listener serviceListener = new (9090);
http:Service httpService = @http:ServiceConfig {} service object {
resource function get baz() returns string {
}
};
public function main() {
error? err1 = serviceListener.attach(httpService, "/foo/bar");
error? err2 = serviceListener.start();
runtime:registerListener(serviceListener);
}

Absolute resource path (basePath)
○ Identiﬁers and String literals are allowed.
○ Starts with “/”
○ Optional and defaults to “/”
service /hello on new http:Listener(9090) {
resource function post test() {
//...
}
}
service “/hello” on new http:Listener(9090) {
resource function post test() {
//...
}
}

Absolute resource path
○ Names with special characters
service http:Service /my/Tes@tHello/go new http:Listener(9090) {
resource function get foo() {
//...
}
}
service http:Service "/Tes@tHello/go" new http:Listener(9090) {
//...
}
}

Resource changes
○ Accessor, Name, Path param, Rest param
○ Signature params such as query, payload, header, caller and
request
○ Return types

Resource methods
○ Resource method has improved in terms of accessor, path and return value
type
resource-accessor-defn := metadata "resource" "function" accessor-name resource-name
function-signature method-defn-body
resource function get foo(string bar) returns http:Response {
http:Response resp = new;
return resp;
}

Resource accessor
○ Conﬁnes the resource to a particular HTTP method
○ In additions to the standard HTTP methods, custom methods are also
supported.
○ default identiﬁer can be used to allow any HTTP method
//...
}
resource function ’default foo() {
//...
}

Resource name
○ The relative path from the absolute path
○ Path identiﬁers separated by “/”
○ Dot identiﬁer is used to denote the “/”
resource function get foo/bar/baz() {
//...
}
service /foo on http:Listener(9090) {
resource function get .() { // curl localhost:9090/foo will get dispatched here
//...
}
}

Path param
○ Include in the resource name itself. string, int, boolean, ﬂoat, decimal types
are supported
resource function get data/[int age]/[string name]/[boolean status]/[float weight]() returns json {
int balAge = age + 1;
float balWeight = weight + 2.95;
string balName = name + " lang";
if (status) {
balName = name;
}
json responseJson = { Name:name, Age:balAge, Weight:balWeight, Status:status, Lang: balName};
return responseJson;
}

Rest param
○ Allows multiple path segments to be dispatched in the absence of a
speciﬁc path. string, int, boolean, ﬂoat, decimal types are supported
○ Rest parameter must be the last segment of resource path
resource function get foo/[string... s]() returns json {
json responseJson = {"echo":s[0]};
return responseJson;
}

Use case: Default resource
○ Allows any HTTP method.
○ Allow any path
resource function 'default [string... s]() returns json {
//...
}

Resource signature parameters
○ No compulsory parameters
○ No annotation required for Query param, Caller and Request
○ New additions - Payload, Header, Query
resource function XXX NAME_TEMPLATE ([@http:CallerInfo {} http:Caller hc], [http:Request
req], [somedatatype queryParam]*, (@http:Payload somedatatype payload)?, (@http:Header
somedatatype header)?) {
//...
}

Conceptual change
○ 1st choice should be to use signature params and use returns. Avoid caller
unless you have specific requirement.
○ Use data binding, header params and resource returns.

Query param
○ Does not associated with any annotation or additional detail. The type of
query param are as follows.
type BasicType boolean|int|float|decimal|string;
public type QueryParamType ()|BasicType|BasicType[];
resource function get q1(int id, string PersoN, float val, boolean isPresent, decimal dc) {
//...
}
resource function get q2(int? id, string[] PersoN, float[]? val) {
//...
}

Payload param
○ The payload parameter eases access of request payload during the
resource invocation. The payload param is deﬁned with @http:Payload
annotation
public type PayloadType string | json | xml | byte[] | record {| anydata...; |}|
record {| anydata...; |}[];
resource function post body(@http:Payload Person person) returns json {
return {"Person": person};
}

Header param
○ The header parameter is to access the request headers The header param
is deﬁned with @http:Header annotation
service sample on new http:Listener(9090) {
//Single header value extraction
resource function post hello1(@http:Header string referer) {
}
//Multiple header value extraction
resource function post hello2(@http:Header {name: "Accept"} string[] accept) {
}
//The http:Header object contains all the headers
resource function get hello3(http:Headers headers) {
String|error referer = headers.getHeader("Referer");
String[]|error accept = headers.getHeaders("Accept");
String[] keys = headers.getHeaderNames();
}
}

CallerInfo annotation
○ The annotation deﬁnes the response payload type.
resource function post foo(@http:CallerInfo {respondType: Person} http:Caller
caller) returns error?{
Person p = {};
error? = caller->respond(p);
}

Resource return type
○ anydata|http:Response|http:StatusCodeResponse|error|()
○ Can decorate with @http:Payload annotation and result in 200 OK
resource function get test() returns @http:Payload {mediaType:"text/id+plain"} string {
return "world";
}
resource function get test2() returns PersonTable[]? {
PersonTable tbPerson = table [
{id: 1, name: "John", salary: 300.50},
{id: 2, name: "Bella", salary: 500.50}
];
return [tbPerson, tbPerson];
}

StatusCodeResponse records
○ Built in records for all status codes
public type Ok record {
readonly StatusOk status;
string mediaType;
map<string|string[]> headers?;
anydata body?;
};
resource function get greeting() returns http:Ok|http:InternalServerError {
http:Ok ok = { body: "hello world", headers: { xtest: "foo"} };
return ok;
}

StatusCodeResponse records
○ Create an inline response
○ Improve readability & helps OpenAPI spec generation
type Person record {
string name;
};
resource function put person(string name) returns record {|*http:Created; Person body;|} {
Person person = {name:name};
return {
mediaType: "application/person+json",
headers: {
"X-Server": "myServer"
},
body: person
};
}

Return nil
○ If resource wants to return nothing, the listener will return 202 Accepted
response
resource function post person(@http:Payload Person p) {
int age = p.age;
io:println(string `Age is: ${age}`);
}

Return nil
○ If the resource is dealt with the response via http:Caller, then returning ()
does not lead to subsequent response. Listener aware that the request is
already being served.
resource function get fruit(string? colour, http:Caller caller) {
if colour == "red" {
error? result = caller->respond("Sending apple");
return; // ending the flow, so not 202 response
}
error? result = caller->respond("Sending orange");
}

Return nil in error case
○ If the resource is dealt with the success response via http:Caller and return
() in the else case, then the response is 500 Internal server error
resource function get fruit(string? colour, http:Caller caller) {
if colour == "red" {
error? result = caller->respond("Sending apple");
return; // ending the flow
}
return; // 500 internal Server Error
}

Return error from the resource
○ Will lead to a 500 internal error and prints the stack trace on the server
console
○ Same applies to the check and checkpanic operations
resource function get info(http:Request request) returns error? {
string value = check request.getHeader("Some-type");
}

HTTP Client changes records
○ Response payload retrieval
○ Headers, Media type arguments

Response payload retrieval
○ The client operation is able to infer the expected payload type from the
LHS variable type
○ Can access the payload as one of the following types:string, json, xml,
byte[], record, record[].
public function main() returns error? {
http:Client httpClient = check new ("https://person.free.beeceptor.com");
json payload = check httpClient->get("/data");
io:println(payload);
}

Response payload retrieval
○ In case of using var as return type, user can pass the typedesc to the
targetType argument
var payload = check httpClient->get("/data", targetType = json);
io:println(payload);
}

Response payload retrieval and 4XX, 5XX responses
○ When the user expects the payload extraction to be happened, the
erroneous HTTP responses (4XX and 5XX status code range) are returned
as ballerina error of the client operation.
http:Client httpClient = check new ("https://www.google.com/");
json|error result = httpClient->get("/wrongPath");
if result is http:ClientRequestError {
io:println(result.message());
}
}

Response payload retrieval and 4XX, 5XX responses
○ When the user expects the payload extraction to be happened, the
erroneous HTTP responses (4XX and 5XX status code range) are returned
as ballerina error of the client operation.
http:Client httpClient = check new ("https://www.google.com/");
json|error result = httpClient->get("/wrongPath");
if result is http:ClientRequestError {
int statusCode = result.detail().statusCode;
anydata payload = result.detail().body;
map<string[]> headers = result.detail().headers;
}
}

Payload binding
○ When the response payload type is JSON, you can simply convert a
compatible payload into ballerina record or record[] by having it as return
type
Person payload = check httpClient->get("/data");
io:println("Hello " + payload.name + "!nJoining from " + payload.address.state);
}

Usual response
○ Whenever user needs to dig into HTTP headers and response properties
along with the payload, it can still be done by having http:Response as the
expected type.
http:Response response = check httpClient->get("/data");
string mediaType = check response.getHeader("Content-type");
io:println("Media: " + mediaType);
io:println("Status: " + response.statusCode.toString());
}

Sending headers in the Client operation
○ Non entity body methods - GET, HEAD, OPTIONS
http:Client httpClient = check new ("https://www.example.com");
map<string|string[]> headers = {
"my-header": "my-header-value",
"header-2": ["foo", "bar"]
};
string resp = check httpClient->get("/data", headers);
}

Sending headers in the Client operation
○ Entity body methods - POST, PUT, DELETE, PATCH
http:Client httpClient = check new ("https://www.example.com");
string response = check httpClient->post("/some/endpoint",
{
name: "foo",
age: 25,
address: "area 51"
},
headers = {
"my-header": "my-header-value"
}
mediaType = "application/json",
);
}

Covered so far
➔ Service,
◆ Declaration, Absolute resource path
➔ Resource
◆ Accessor, Name, Path param, Rest param
◆ Signature param such as query, payload, header, caller and
request
◆ Return types
➔ Client
◆ Response payload retrieval
◆ Headers, Media type arguments in client operation

HTTP Security
Service
● Transport Layer Security
○ SSL/TLS
○ mTLS
● Application Layer Security
○ Basic auth
■ File user store
■ LDAP user store
○ JWT auth
○ OAuth2
Client
● Transport Layer Security
○ SSL/TLS
○ mTLS
● Application Layer Security
○ Basic auth
○ JWT auth
■ Bearer token
■ Self signed token
○ OAuth2
■ Bearer token
■ Client credentials grant type
■ Password grant type
■ Refresh token grant type

How to configure service? import ballerina/http;
listener http:Listener securedEP = new(9090,
secureSocket = {
// ...
}
);
@http:ServiceConfig {
auth: [
// ...
]
}
service /foo on securedEP {
@http:ResourceConfig {
auth: [
// ...
]
}
resource function get bar() returns string {
return "Hello, World!";
}
}
○ Listener configurations
○ Secure socket config
○ Service configurations
○ Auth config
○ Resource configurations
○ Auth config

How to configure client? import ballerina/http;
http:Client securedEP = check new("https://localhost:9090",
secureSocket = {
// ...
},
auth = {
// ...
}
);
string response = check securedEP->get("/foo/bar");
io:println(response);
}
○ Client configurations
○ Secure socket config
○ Auth config

HTTP Service
Transport Layer Security

Service - SSL/TLS import ballerina/http;
secureSocket = {
key: {
certFile: "/path/to/public.crt",
keyFile: "/path/to/private.key"
}
}
);
}
}

Service - mTLS import ballerina/http;
secureSocket = {
key: {
},
mutualSsl: {
cert: "/path/to/client-public.crt"
}
}
);
}
}

HTTP Service
Application Layer Security
Authentication

Service - Basic auth
(File user store)
import ballerina/http;
secureSocket = {
key: {
}
}
);
auth: [
{
fileUserStoreConfig: {}
}
]
}
}
}
Conﬁg.toml
[[ballerina.auth.users]]
username="alice"
password="alice@123"
scopes=["developer"]
username="bob"
password="bob@123"
scopes=["developer", "admin"]

Service - Basic auth
(LDAP user store)
secureSocket = {
key: {
}
}
);
auth: [
{
ldapUserStoreConfig: {
domainName: "avix.lk",
connectionUrl: "ldap://localhost:389",
// ...
}
}
]
}
}
}

Service - JWT auth
Signature validation
○ Public certiﬁcate
signatureConfig: {
certFile: "/path/to/public.crt"
}
○ Truststore
trustStoreConfig: {
trustStore: {
path: "/path/to/truststore.p12",
password: "password"
},
certAlias: "alias"
}
secureSocket = {
key: {
}
}
);
auth: [
{
jwtValidatorConfig: {
issuer: "wso2",
audience: "ballerina",
signatureConfig: {
}
}
}
]
}
}
}

Service - OAuth2 import ballerina/http;
secureSocket = {
key: {
}
}
);
auth: [
{
oauth2IntrospectionConfig: {
url: "https://localhost:9445/oauth2/introspect",
tokenTypeHint: "access_token"
clientConfig: {
secureSocket: {
cert: "/path/to/public.crt"
}
}
}
}
]
}
}
}

HTTP Service
Authorization

Service - JWT auth import ballerina/http;
secureSocket = {
key: {
}
}
);
auth: [
{
jwtValidatorConfig: {
issuer: "wso2",
signatureConfig: {
}
},
scopes: ["admin"],
}
]
}
}
}

HTTP Client
Transport Layer Security

Client - SSL/TLS import ballerina/http;
import ballerina/io;
secureSocket = {
}
);
}

Client - mTLS import ballerina/http;
secureSocket = {
key: {
certFile: "/path/to/server-public.crt",
keyFile: "/path/to/server-private.key"
},
}
);
}

HTTP Client

Client - Basic auth import ballerina/http;
auth = {
username: "alice",
password: "alice@123"
},
secureSocket = {
cert: "../resource/path/to/public.crt"
}
);
}

Client - JWT auth import ballerina/http;
auth = {
token: "eyJhbGciOiJSUzI1NiIsICJ0eXAiOiJKV1QifQ...."
},
secureSocket = {
}
);
}
○ Bearer token
○ Self-signed token

Client - JWT auth import ballerina/http;
auth = {
username: "ballerina",
issuer: "wso2",
audience: ["ballerina", "ballerina.io"],
keyId: "5a0b754-895f-4279-8843-b745e11a57e9",
jwtId: "JlbmMiOiJBMTI4Q0JDLUhTMjU2In",
customClaims: { "scp": "admin" },
expTime: 3600,
signatureConfig: {
config: {
}
}
},
secureSocket = {
}
);
}
○ Bearer token
○ Self-signed token

Client - OAuth2 import ballerina/http;
auth = {
token: "56ede317-4511-44b4-8579-a08f094ee8c5"
},
secureSocket = {
}
);
}
○ Bearer token
○ Client credentials grant type
○ Password grant type
○ Refresh token grant type

auth = {
tokenUrl: "https://localhost:9445/oauth2/token",
clientId: "FlfJYKBD2c925h4lkycqNZlC2l4a",
clientSecret: "PJz0UhTJMrHOo68QQNpvnqAY_3Aa",
scopes: ["admin"],
clientConfig: {
secureSocket: {
}
}
},
secureSocket = {
}
);
}
○ Bearer token

auth = {
tokenUrl: "https://localhost:9445/oauth2/token",
username: "admin",
password: "admin",
scopes: ["admin"],
refreshConfig: {
refreshUrl: "https://localhost:9445/oauth2/token",
scopes: ["hello"],
clientConfig: {
secureSocket: {
}
}
},
clientConfig: {
secureSocket: {
}
}
},
secureSocket = {
}
);
}
○ Bearer token

auth = {
refreshUrl: "https://localhost:9445/oauth2/token",
refreshToken: "24f19603-8565-4b5f-a036-88a945e1f272",
scopes: ["admin"],
clientConfig: {
secureSocket: {
}
}
},
secureSocket = {
}
);
}
○ Bearer token

Service - JWT auth (Imperative method)
import ballerina/jwt;
secureSocket = {
key: {
}
}
);
http:ListenerJwtAuthHandler handler = new({
issuer: "wso2",
signatureConfig: {
},
scopeKey: "scp"
});

Service - JWT auth (Imperative method)
resource function get bar(@http:Header { name: "Authorization" } string header) returns
string|http:Unauthorized|http:Forbidden {
jwt:Payload|http:Unauthorized authn = handler.authenticate(header);
if (authn is http:Unauthorized) {
return authn;
}
http:Forbidden? authz = handler.authorize(<jwt:Payload> authn, ["write", "update"]);
if (authz is http:Forbidden) {
return authz;
}
}
}

[Community Call] Ballerina Swan Lake HTTP Module Changes

More Related Content

Similar to [Community Call] Ballerina Swan Lake HTTP Module Changes

More from Ballerinalang

Recently uploaded

[Community Call] Ballerina Swan Lake HTTP Module Changes