Skip to content

plgd-dev/client-application

Repository files navigation

CI Quality Gate Status codecov

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".