![codecov](https://codecov.io/gh/plgd-dev/client-application/branch/main/graph/badge.svg)
Client Application
Provides GRPC and HTTP APIs to interact with the OCF devices via D2D communication.
Run
The client application can be run by executing the following command:
./client-application
- Default
config.yaml
file will be generated in case it's not in the same directory as the client application, or if a different path with the existing config isn't specified.
- Default web UI files will be copied to the
www
folder next to the client application in case it doesn't exist, or if a different path with existing UI files isn't specified in the config file.
Supported options
--config
: path to the config file
--version
: print the version of the client application
Build
The build process uses goreleaser, so you will need to commit all changes and create a tag on the local machine.
git commit -a -m "my changes"
git tag -f v0.0.1-myversion
make build
Docker
You can run the client application in a docker container by executing the following command.
docker run --rm -it -e NUM_DEVICES=1 -p 8080:8080 ghcr.io/plgd-dev/client-application:latest
Via environment variable NUM_DEVICES you can specify the number of devices simulators. The default value is 1. The client application will be available at http://locahost:8080.
YAML Configuration
A configuration template is available on config.yaml.
Logging
Property |
Type |
Description |
Default |
log.dumpBody |
bool |
Set to true if you would like to dump raw messages. |
false |
log.level |
string |
Logging enabled from level. |
"info" |
log.encoding |
string |
Logging format. The supported values are: "json", "console" |
"console" |
log.stacktrace.enabled |
bool |
Log stacktrace. |
"false |
log.stacktrace.level |
string |
Stacktrace from level. |
"warn |
log.encoderConfig.timeEncoder |
string |
Time format for logs. The supported values are: "rfc3339nano", "rfc3339". |
"rfc3339nano |
HTTP API
HTTP API of the client application service as defined swagger.
Property |
Type |
Description |
Default |
apis.http.enabled |
bool |
Enable the HTTP API. |
true |
apis.http.cors.allowedOrigins |
[]string |
Sets the allowed origins for CORS requests, as used in the 'Allow-Access-Control-Origin' HTTP header. Passing in a "*" will allow any domain. |
"*" |
apis.http.cors.allowedHeaders |
[]string |
Adds the provided headers to the list of allowed headers in a CORS request. This is an append operation so the headers Accept, Accept-Language, and Content-Language are always allowed. Content-Type must be explicitly declared if accepting Content-Types other than application/x-www-form-urlencoded, multipart/form-data, or text/plain. |
"Accept","Accept-Language","Accept-Encoding","Content-Type","Content-Language","Content-Length","Origin","X-CSRF-Token","Authorization" |
apis.http.cors.allowedMethods |
[]string |
Explicitly set allowed methods in the Access-Control-Allow-Methods header. This is a replacement operation so you must also pass GET, HEAD, and POST if you wish to support those methods. |
"GET","PATCH","HEAD","POST","PUT","OPTIONS","DELETE" |
apis.http.cors.allowCredentials |
bool |
User agent may pass authentication details along with the request. |
false |
apis.http.address |
string |
Listen specification <host>:<port> for http client connection. |
"0.0.0.0:8080" |
apis.http.readTimeout |
string |
The maximum duration for reading the entire request, including the body by the server. A zero or negative value means there will be no timeout. |
8s |
apis.http.readHeaderTimeout |
string |
The amount of time allowed to read request headers by the server. If readHeaderTimeout is zero, the value of readTimeout is used. If both are zero, there is no timeout. |
4s |
apis.http.writeTimeout |
string |
The maximum duration before the server times out writing of the response. A zero or negative value means there will be no timeout. |
16s |
apis.http.idleTimeout |
string |
The maximum amount of time the server waits for the next request when keep-alives are enabled. If idleTimeout is zero, the value of readTimeout is used. If both are zero, there is no timeout. |
30s |
apis.http.ui.enabled |
bool |
Set to true if you would like to run the web UI. |
false |
apis.http.ui.directory |
string |
A path to the directory with web UI files. When it is not present, it creates <client_application_binary>/www with default ui. |
"" |
apis.http.tls.enabled |
bool |
Enable HTTPS. |
false |
apis.http.tls.caPool |
[]string |
File path to the root certificate in PEM format which might contain multiple certificates in a single file. |
"" |
apis.http.tls.keyFile |
string |
File path to private key in PEM format. |
"" |
apis.http.tls.certFile |
string |
File path to certificate in PEM format. |
"" |
apis.http.tls.clientCertificateRequired |
bool |
If true, require client certificate. |
true |
gRPC API
gRPC API of the client application service as defined service.
Property |
Type |
Description |
Default |
apis.grpc.enabled |
bool |
Enable the GRPC API. |
true |
apis.grpc.address |
string |
Listen specification <host>:<port> for grpc client connection. |
"0.0.0.0:8081" |
apis.grpc.enforcementPolicy.minTime |
string |
The minimum amount of time a client should wait before sending a keepalive ping. Otherwise the server close connection. |
5s |
apis.grpc.enforcementPolicy.permitWithoutStream |
bool |
If true, server allows keepalive pings even when there are no active streams(RPCs). Otherwise the server close connection. |
false |
apis.grpc.keepAlive.maxConnectionIdle |
string |
A duration for the amount of time after which an idle connection would be closed by sending a GoAway. 0s means infinity. |
0s |
apis.grpc.keepAlive.maxConnectionAge |
string |
A duration for the maximum amount of time a connection may exist before it will be closed by sending a GoAway. 0s means infinity. |
0s |
apis.grpc.keepAlive.maxConnectionAgeGrace |
string |
An additive period after MaxConnectionAge after which the connection will be forcibly closed. 0s means infinity. |
0s |
apis.grpc.keepAlive.time |
string |
After a duration of this time if the server doesn't see any activity it pings the client to see if the transport is still alive. |
2h |
apis.grpc.keepAlive.timeout |
string |
After having pinged for keepalive check, the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed. |
20s |
apis.grpc.tls.caPool |
[]string |
File path to the root certificate in PEM format which might contain multiple certificates in a single file. |
"" |
apis.grpc.tls.enabled |
bool |
Enable TLS for grpc. |
false |
apis.grpc.tls.keyFile |
string |
File path to private key in PEM format. |
"" |
apis.grpc.tls.certFile |
string |
File path to certificate in PEM format. |
"" |
apis.grpc.tls.clientCertificateRequired |
bool |
If true, require client certificate. |
true |
Device client
The configuration sets up access to the devices via COAP protocol.
Property |
Type |
Description |
Default |
apis.coap.maxMessageSize |
int |
Max message size which can be sent/received via coap. i.e. 256*1024 = 262144 bytes. |
262144 |
apis.coap.inactivityMonitor.timeout |
string |
Time limit to close inactive connection. |
20s |
apis.coap.blockwiseTransfer.enabled |
bool |
If true, enable blockwise transfer of coap messages. |
false |
apis.coap.blockwiseTransfer.blockSize |
int |
Size of blockwise transfer block. |
1024 |
apis.coap.ownershipTransfer.methods |
[]string |
Allowed ownership transfer methods. The supported values are: "justWorks", "manufacturerCertificate". |
"justWorks" |
apis.coap.ownershipTransfer.manufacturerCertificate.tls.caPool |
[]string |
File paths to the root certificates in PEM format. The file may contain multiple certificates. |
"" |
apis.coap.ownershipTransfer.manufacturerCertificate.tls.keyFile |
string |
File path to certificate client application private key in PEM format. |
"" |
apis.coap.ownershipTransfer.manufacturerCertificate.tls.certFile |
string |
File path to certificate client application certificate in PEM format. |
"" |
apis.coap.tls.preSharedKey.subjectId |
string |
Provides an identifier for client applications for establishing TLS connections or for devices that are set as owner devices |
"" |
apis.coap.tls.preSharedKey.key |
string |
Pre-shared key used in conjunction with subjectId to enable TLS connection. |
"" |
Remote provisioning
The configuration sets up ownership and authorization of devices via the remote provisioning mode.
Supported modes:
Property |
Type |
Description |
Default |
remoteProvisioning.mode |
string |
Provides remote provisioning mode. In "userAgent" mode all signing certificates goes through the user agent (browser,cli). "" means none. The supported values are: "", "userAgent" |
"" |
remoteProvisioning.certificateAuthority |
string |
Certificate authority server address in format {SCHEME}://{DNS}:{PORT} |
"" |
remoteProvisioning.userAgent.csrChallengeStateExpiration |
string |
Defines how long is valid csr challenge. |
"1m" |
remoteProvisioning.authority |
string |
Authority is the address of the token-issuing authentication server. |
"" |
remoteProvisioning.webOAuthClient.clientID |
string |
Client ID to exchange an authorization code for an access token. |
"" |
remoteProvisioning.webOAuthClient.audience |
string |
Identifier of the API configured in your OAuth provider. |
"" |
remoteProvisioning.webOAuthClient.scopes |
[]string |
List of required scopes. |
[] |
remoteProvisioning.ownerClaim |
string |
Claim used to identify owner of the device. |
"sub" |
remoteProvisioning.hubID |
string |
Plgd hub id. |
"" |
remoteProvisioning.coapGateway |
string |
CoAP gateway for onboard device. |
"" |
remoteProvisioning.caPool |
[]string |
File paths to root CAs which was used to sign coap-gw certificate. |
"" |
remoteProvisioning.deviceOAuthClient.clientID |
string |
Client ID to exchange an authorization code for an access token. |
"" |
remoteProvisioning.deviceOAuthClient.audience |
string |
Identifier of the API configured in your OAuth provider. |
"" |
remoteProvisioning.deviceOAuthClient.scopes |
[]string |
List of required scopes. |
[] |
remoteProvisioning.deviceOAuthClient.providerName |
string |
Name of provider, which needs to be set to cloud resource during cloud provisioning. |
"" |
Note that the string type related to time (i.e. timeout, idleConnTimeout, expirationTime) is decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us", "ms", "s", "m", "h".