trait DeclarativeApi[Cfg, Prep] extends DeclarativeApiHandle[Cfg] with NamedLogging
Base classes to synchronize a state in a file with the state managed through the admin api
The admin api for Canton is imperative, which allows us to manage large states, but it makes simple deployments more complex. In such cases, the declarative API allows to define the desired state in a config file, with a process that will in the background attempt to change the node state accordingly.
- Alphabetic
- By Inheritance
- DeclarativeApi
- NamedLogging
- DeclarativeApiHandle
- AnyRef
- Any
- Hide All
- Show All
- Public
- Protected
Abstract Value Members
- abstract def activeAdminToken: Option[CantonAdminToken]
- Attributes
- protected
- abstract def closeContext: CloseContext
- Attributes
- protected
- abstract def consistencyTimeout: NonNegativeDuration
- Attributes
- protected
- implicit abstract def executionContext: ExecutionContext
- Attributes
- protected
- abstract def loggerFactory: NamedLoggerFactory
- Attributes
- protected
- Definition Classes
- NamedLogging
- abstract def metrics: DeclarativeApiMetrics
- Attributes
- protected
- abstract def name: String
- Attributes
- protected
- abstract def prepare(config: Cfg)(implicit traceContext: TraceContext): Either[String, Prep]
- Attributes
- protected
- abstract def sync(config: Cfg, prep: Prep)(implicit traceContext: TraceContext): Either[String, UpdateResult]
- Attributes
- protected
Concrete Value Members
- final def !=(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
- final def ##: Int
- Definition Classes
- AnyRef → Any
- final def ==(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
- final def asInstanceOf[T0]: T0
- Definition Classes
- Any
- def clone(): AnyRef
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.CloneNotSupportedException]) @IntrinsicCandidate() @native()
- lazy val currentConfig: AtomicReference[Cfg]
- Attributes
- protected
- final def eq(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- def equals(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef → Any
- implicit def errorLoggingContext(implicit traceContext: TraceContext): ErrorLoggingContext
- Attributes
- protected
- Definition Classes
- NamedLogging
- final def fetchAll[S](request: (PositiveInt) => Either[String, Seq[S]], lessThan: PositiveInt = startLimit): Either[String, Seq[S]]
- Attributes
- protected
- final def getClass(): Class[_ <: AnyRef]
- Definition Classes
- AnyRef → Any
- Annotations
- @IntrinsicCandidate() @native()
- def hashCode(): Int
- Definition Classes
- AnyRef → Any
- Annotations
- @IntrinsicCandidate() @native()
- def invalidConfig()(implicit traceContext: TraceContext): Unit
- Definition Classes
- DeclarativeApi → DeclarativeApiHandle
- final def isInstanceOf[T0]: Boolean
- Definition Classes
- Any
- def logger: TracedLogger
- Attributes
- protected
- Definition Classes
- NamedLogging
- implicit def namedLoggingContext(implicit traceContext: TraceContext): NamedLoggingContext
- Attributes
- protected
- Definition Classes
- NamedLogging
- final def ne(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- def newConfig(cfg: Cfg)(implicit traceContext: TraceContext): Boolean
- Definition Classes
- DeclarativeApi → DeclarativeApiHandle
- def noTracingLogger: Logger
- Attributes
- protected
- Definition Classes
- NamedLogging
- final def notify(): Unit
- Definition Classes
- AnyRef
- Annotations
- @IntrinsicCandidate() @native()
- final def notifyAll(): Unit
- Definition Classes
- AnyRef
- Annotations
- @IntrinsicCandidate() @native()
- def poke()(implicit traceContext: TraceContext): Unit
- Definition Classes
- DeclarativeApi → DeclarativeApiHandle
- def run[K, V](name: String, removeExcess: Boolean, checkSelfConsistent: Boolean, want: Seq[(K, V)], fetch: (PositiveInt) => Either[String, Seq[(K, V)]], add: (K, V) => Either[String, Unit], upd: (K, V, V) => Either[String, Unit], rm: (K, V) => Either[String, Unit], compare: Option[(V, V) => Boolean] = None, await: Option[(Seq[K]) => Either[String, Boolean]] = None, onlyCheckKeys: Boolean = false)(implicit traceContext: TraceContext): Either[String, UpdateResult]
Generic self-consistency update runner
Generic self-consistency update runner
This function can be used to determine and apply a set of changes to a system. We generally refer to the state on a per key basis (e.g. user name, party name, dar-id etc). Each key points to a value. So effectively, we compare for each key whether the values match and if they don't, we update the state such that they do.
- name
the name of the operation (e.g. dars, parties)*
- removeExcess
if true, then items which are on the node but not found in the config will be removed. this is off by default to ensure that state that has been added via the admin api is not deleted.
- checkSelfConsistent
if true (default), then the system will check whether it successfully updated the rows by checking the state after an update and verifying that it matches now the "wanted" state.
- want
the state as desired
- fetch
a function to fetch the current state. the function takes a limit argument. If the fetch returns the max limit, we assume that we need to fetch more. The system will start to emit warnings but increase the fetch limit to remain functional but to warn the user that they are reaching the limits of managing a node through a config file.
- add
if the runner finds a value (K,V) in the want set which is not in the have set, it will invoke the add function.
- upd
if the runner finds a value (K,V) where the want value V differs from the current have value V', then the update function is invoked. The first V is the desired, the second is the existing state.
- rm
if removeExcess is set to true and the runner finds a K in the have set but not in the want set, it will invoke the rm function to remove K.
- compare
supply distinct comparison function that checks whether an update is necessary (in case x:V \== y:V) needs adjustment
- await
the await function can be used to wait for a specific result after the update cycle (concretely, we wait for the ledger api server to observe the parties before we start adding users that refer to these parties)
- Attributes
- protected
- final def runSync()(implicit traceContext: TraceContext): Boolean
Trigger a synchronisation
Trigger a synchronisation
This method is thread safe as it will only run one synchronisation at a time (managed through an atomic reference). If no sync is currently running, the method will return only when the sync is finished. If a sync is already running, the method will return immediately.
Concurrent sync runs are very rare, but can happen if the file is changed while a manual synchronizer connection is being added via the console commands or if the sync is currently failing due to a config issue or a bug.
- Annotations
- @tailrec()
- final def synchronized[T0](arg0: => T0): T0
- Definition Classes
- AnyRef
- def toString(): String
- Definition Classes
- AnyRef → Any
- final def wait(arg0: Long, arg1: Int): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException])
- final def wait(arg0: Long): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException]) @native()
- final def wait(): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException])
- def withRetry(action: => Either[String, Boolean], description: String)(implicit traceContext: TraceContext, executionContext: ExecutionContext): Either[String, Unit]
- Attributes
- protected