diff --git a/seq-api.sln.DotSettings b/seq-api.sln.DotSettings index 6e98e3d..f2b88bf 100644 --- a/seq-api.sln.DotSettings +++ b/seq-api.sln.DotSettings @@ -2,15 +2,27 @@ AD True True + True True + True + True True + True + True True True True True True + True + True True True + True + True + True + True True + True True diff --git a/src/Seq.Api/Model/AppInstances/AppInstanceEntity.cs b/src/Seq.Api/Model/AppInstances/AppInstanceEntity.cs index 380771a..ea7558f 100644 --- a/src/Seq.Api/Model/AppInstances/AppInstanceEntity.cs +++ b/src/Seq.Api/Model/AppInstances/AppInstanceEntity.cs @@ -1,13 +1,37 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; using System.Collections.Generic; using Newtonsoft.Json; using Seq.Api.Model.Apps; using Seq.Api.Model.Signals; +using Seq.Api.ResourceGroups; namespace Seq.Api.Model.AppInstances { + /// + /// App instances are individual processes based on a running that can + /// read from and write to the Seq event stream. + /// public class AppInstanceEntity : Entity { + /// + /// Construct an with default values. + /// + /// Instead of constructing an instance directly, consider using + /// to obtain a partly-initialized instance. public AppInstanceEntity() { Settings = new Dictionary(); @@ -17,8 +41,19 @@ public AppInstanceEntity() Metrics = new AppInstanceMetricsPart(); } + /// + /// The id of the that this is an instance of. + /// public string AppId { get; set; } + + /// + /// The user-friendly title of the app instance. + /// public string Title { get; set; } + + /// + /// Values for the settings exposed by the app. + /// public Dictionary Settings { get; set; } /// @@ -32,25 +67,67 @@ public AppInstanceEntity() /// as the target for alert notifications. /// public bool AcceptDirectInvocation { get; set; } + + /// + /// The settings that can be overridden at invocation time (when an event is sent to + /// the instance). + /// public List InvocationOverridableSettings { get; set; } + + /// + /// Metadata describing the overridable settings. This field is provided by the server + /// and cannot be modified. + /// public List InvocationOverridableSettingDefinitions { get; set; } /// - /// If true, events will be streamed to the app. + /// If true, events will be streamed to the app. Otherwise, events will be + /// sent only manually or in response to alerts being triggered. /// public bool AcceptStreamedEvents { get; set; } + + /// + /// The signal expression describing which events will be sent to the app; if null, + /// all events will reach the app. + /// public SignalExpressionPart InputSignalExpression { get; set; } + + /// + /// If a value is specified, events will be buffered to disk and sorted by timestamp-order + /// within the specified window. This is not recommended for performance reasons, and should + /// be avoided when possible. + /// public TimeSpan? ArrivalWindow { get; set; } + + /// + /// The time after an event reaches the app during which no further events will be processed. + /// The default indicates no suppression time, and all events + /// will be processed in that case. + /// public TimeSpan SuppressionTime { get; set; } + + /// + /// If is set, the number of events that will be allowed during the + /// suppression window. The default is 1, to allow only the initial event that triggered suppression. + /// public int EventsPerSuppressionWindow { get; set; } + /// + /// Metrics describing the state and activity of the app. + /// [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)] public AppInstanceMetricsPart Metrics { get; set; } + /// + /// Obsolete. + /// [Obsolete("Use !AcceptStreamedEvents instead. This field will be removed in Seq 6.0.")] [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)] public bool? IsManualInputOnly { get; set; } + /// + /// Obsolete. + /// [Obsolete("Use !AcceptDirectInvocation instead. This field will be removed in Seq 6.0.")] [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)] public bool? DisallowManualInput { get; set; } diff --git a/src/Seq.Api/Model/AppInstances/AppInstanceMetricsPart.cs b/src/Seq.Api/Model/AppInstances/AppInstanceMetricsPart.cs index 0f94b74..a164809 100644 --- a/src/Seq.Api/Model/AppInstances/AppInstanceMetricsPart.cs +++ b/src/Seq.Api/Model/AppInstances/AppInstanceMetricsPart.cs @@ -1,10 +1,43 @@ -namespace Seq.Api.Model.AppInstances +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.AppInstances { + /// + /// Metrics describing an . + /// public class AppInstanceMetricsPart { + /// + /// The number of events that reached the app in the past minute. + /// public int ReceivedEventsPerMinute { get; set; } + + /// + /// The number of diagnostic events raised by the app in the past minute. + /// + /// This does not include the events received by an input app. public int EmittedEventsPerMinute { get; set; } + + /// + /// The size, in bytes, of the app process working set. + /// public long ProcessWorkingSetBytes { get; set; } + + /// + /// If the app process is running, true; otherwise, false. + /// public bool IsRunning { get; set; } } } diff --git a/src/Seq.Api/Model/Apps/AppEntity.cs b/src/Seq.Api/Model/Apps/AppEntity.cs index 1deae4a..f7a260e 100644 --- a/src/Seq.Api/Model/Apps/AppEntity.cs +++ b/src/Seq.Api/Model/Apps/AppEntity.cs @@ -1,25 +1,62 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + using System.Collections.Generic; -using Newtonsoft.Json; +using Seq.Api.ResourceGroups; namespace Seq.Api.Model.Apps { + /// + /// Seq apps are executable plug-ins that read from and write to the Seq event stream. + /// public class AppEntity : Entity { + /// + /// Construct an with default values. + /// + /// Instead of constructing an instance directly, consider using + /// to obtain a partly-initialized instance. public AppEntity() { Name = "New App"; AvailableSettings = new List(); } + /// + /// The friendly name of the app. + /// public string Name { get; set; } + /// + /// A long-form description of the app. + /// public string Description { get; set; } + /// + /// Metadata describing the settings exposed by instances of the app. + /// public List AvailableSettings { get; set; } + /// + /// Whether instances of the app can safely process their own diagnostic events. The + /// default is false. This option should not normally be set. + /// public bool AllowReprocessing { get; set; } + /// + /// Metadata describing the NuGet package containing the executable app components. + /// public AppPackagePart Package { get; set; } /// diff --git a/src/Seq.Api/Model/Apps/AppPackagePart.cs b/src/Seq.Api/Model/Apps/AppPackagePart.cs index cb99313..42b28fe 100644 --- a/src/Seq.Api/Model/Apps/AppPackagePart.cs +++ b/src/Seq.Api/Model/Apps/AppPackagePart.cs @@ -1,13 +1,59 @@ -namespace Seq.Api.Model.Apps +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using Seq.Api.Model.Feeds; + +namespace Seq.Api.Model.Apps { + /// + /// Describes a NuGet package containing executable app components. + /// public class AppPackagePart { + /// + /// The id of the from which the package was installed. + /// public string NuGetFeedId { get; set; } + + /// + /// The package id, for example Seq.Input.HealthCheck. + /// public string PackageId { get; set; } + + /// + /// The version of the package. + /// public string Version { get; set; } + + /// + /// Package authorship information. + /// public string Authors { get; set; } + + /// + /// URL of an icon for the app package. + /// public string IconUrl { get; set; } + + /// + /// URL of the package license. + /// public string LicenseUrl { get; set; } + + /// + /// Whether an update is known to be available for the app. + /// public bool UpdateAvailable { get; set; } } } diff --git a/src/Seq.Api/Model/Apps/AppSettingPart.cs b/src/Seq.Api/Model/Apps/AppSettingPart.cs index 8356c87..ddc21bc 100644 --- a/src/Seq.Api/Model/Apps/AppSettingPart.cs +++ b/src/Seq.Api/Model/Apps/AppSettingPart.cs @@ -1,11 +1,50 @@ -namespace Seq.Api.Model.Apps +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Apps { + /// + /// Describes a setting exposed by instances of an . + /// public class AppSettingPart { + /// + /// The unique name identifying the setting. + /// public string Name { get; set; } + + /// + /// A friendly, descriptive name of the setting. + /// public string DisplayName { get; set; } + + /// + /// Whether the setting is required in order for the app to function. + /// public bool IsOptional { get; set; } + + /// + /// Long-form description of the setting. + /// public string HelpText { get; set; } + + /// + /// The type of value accepted for the setting; valid values are Text, + /// LongText, Checkbox, Integer, Decimal, and Password. + /// + /// An enum was historically not used here in order to improve + /// forwards/backwards compatibility. public string Type { get; set; } } } diff --git a/src/Seq.Api/Model/Backups/BackupEntity.cs b/src/Seq.Api/Model/Backups/BackupEntity.cs index 4631a56..3823b2c 100644 --- a/src/Seq.Api/Model/Backups/BackupEntity.cs +++ b/src/Seq.Api/Model/Backups/BackupEntity.cs @@ -1,9 +1,40 @@ -namespace Seq.Api.Model.Backups +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Backups { + /// + /// Seq backups include metadata like users, signals, API keys and other configuration, but do not include + /// the event stream. Backups are fully encrypted with AES-256 and cannot be restored without the master key + /// from the originating Seq instance. + /// public class BackupEntity : Entity { + /// + /// The time at which the backup was created (ISO-8601-encoded date/time). + /// public string CreatedAt { get; set; } + + /// + /// The filename (without path information) of the backup, within the server's + /// configured backup location. + /// public string Filename { get; set; } + + /// + /// The size, in bytes, of the backup file. + /// public long FileSizeBytes { get; set; } } } diff --git a/src/Seq.Api/Model/Data/QueryExecutionStatisticsPart.cs b/src/Seq.Api/Model/Data/QueryExecutionStatisticsPart.cs index c0c030b..5a7e8c7 100644 --- a/src/Seq.Api/Model/Data/QueryExecutionStatisticsPart.cs +++ b/src/Seq.Api/Model/Data/QueryExecutionStatisticsPart.cs @@ -1,10 +1,43 @@ +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + namespace Seq.Api.Model.Data { + /// + /// Information describing the execution of a SQL-style query. + /// public class QueryExecutionStatisticsPart { + /// + /// The number of events inspected in the course of computing the query result. This will + /// not include events that could be skipped based on index information or text pre-filtering. + /// public long ScannedEventCount { get; set; } + + /// + /// The number of events that contributed to the query result. + /// public long MatchingEventCount { get; set; } + + /// + /// Whether the query needed to search disk-backed storage. + /// public bool UncachedSegmentsScanned { get; set; } + + /// + /// The server-side elapsed time taken to compute the query result. + /// public double ElapsedMilliseconds { get; set; } } } \ No newline at end of file diff --git a/src/Seq.Api/Model/Data/QueryResultPart.cs b/src/Seq.Api/Model/Data/QueryResultPart.cs index 3a61136..81bb654 100644 --- a/src/Seq.Api/Model/Data/QueryResultPart.cs +++ b/src/Seq.Api/Model/Data/QueryResultPart.cs @@ -1,31 +1,77 @@ +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + using Newtonsoft.Json; namespace Seq.Api.Model.Data { + /// + /// The result of executing a SQL-style query. Results are hierarchical, rather + /// than tabular, to reduce the amount of data transfer required to send events to + /// the client. + /// + /// + /// Only one of , , or + /// will be present for a given result set. + /// Generally, the CSV-based query endpoints are more convenient to use for + /// simple ETL tasks. public class QueryResultPart { + /// + /// The columns within the result set (at various levels of the hierarchy). + /// public string[] Columns { get; set; } + /// + /// Result rows. + /// [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)] public object[][] Rows { get; set; } - // or + + /// + /// Result time slices. + /// [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)] public TimeSlicePart[] Slices { get; set; } - // or + + /// + /// Result timeseries. + /// [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)] public TimeseriesPart[] Series { get; set; } - // On error only: - + /// + /// On error only, a description of the error. + /// [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)] public string Error { get; set; } + /// + /// Reasons for the . + /// [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)] public string[] Reasons { get; set; } + /// + /// A corrected version of the query, if one could be suggested. + /// [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)] public string Suggestion { get; set; } + /// + /// Execution statistics. + /// [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)] public QueryExecutionStatisticsPart Statistics { get; set; } } diff --git a/src/Seq.Api/Model/Data/TimeSlicePart.cs b/src/Seq.Api/Model/Data/TimeSlicePart.cs index 057ef32..32f7b93 100644 --- a/src/Seq.Api/Model/Data/TimeSlicePart.cs +++ b/src/Seq.Api/Model/Data/TimeSlicePart.cs @@ -1,8 +1,33 @@ +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + namespace Seq.Api.Model.Data { + /// + /// Results of a query for a given time slice. + /// public class TimeSlicePart { + /// + /// The beginning of the interval contributing to the results, + /// encoded as an ISO-8601 date/time string. + /// public string Time { get; set; } + + /// + /// Result rows within the interval. + /// public object[][] Rows { get; set; } } } \ No newline at end of file diff --git a/src/Seq.Api/Model/Data/TimeseriesPart.cs b/src/Seq.Api/Model/Data/TimeseriesPart.cs index 4ed8bf3..058dad5 100644 --- a/src/Seq.Api/Model/Data/TimeseriesPart.cs +++ b/src/Seq.Api/Model/Data/TimeseriesPart.cs @@ -1,8 +1,32 @@ +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + namespace Seq.Api.Model.Data { + /// + /// A series of results. + /// public class TimeseriesPart { + /// + /// The key (e.g. grouping columns) that identify the timeseries. + /// public object[] Key { get; set; } + + /// + /// The timestamped slices in the series. + /// public TimeSlicePart[] Slices { get; set; } } } \ No newline at end of file diff --git a/src/Seq.Api/Model/Diagnostics/RunningTaskPart.cs b/src/Seq.Api/Model/Diagnostics/RunningTaskPart.cs index 8565b84..5274276 100644 --- a/src/Seq.Api/Model/Diagnostics/RunningTaskPart.cs +++ b/src/Seq.Api/Model/Diagnostics/RunningTaskPart.cs @@ -1,11 +1,39 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; namespace Seq.Api.Model.Diagnostics { + /// + /// Describes a task being actively performed by the Seq server. + /// public class RunningTaskPart { + /// + /// A unique identifier for the task. + /// public Guid Id { get; set; } + + /// + /// A description of the task. + /// public string Description { get; set; } + + /// + /// When the task started. + /// public DateTime StartedAtUtc { get; set; } } } \ No newline at end of file diff --git a/src/Seq.Api/Model/Diagnostics/ServerMetricsEntity.cs b/src/Seq.Api/Model/Diagnostics/ServerMetricsEntity.cs index f46dcb9..2865050 100644 --- a/src/Seq.Api/Model/Diagnostics/ServerMetricsEntity.cs +++ b/src/Seq.Api/Model/Diagnostics/ServerMetricsEntity.cs @@ -1,41 +1,138 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; using System.Collections.Generic; namespace Seq.Api.Model.Diagnostics { + /// + /// Metrics describing the state and performance of the Seq server. + /// public class ServerMetricsEntity : Entity { + /// + /// Construct a . + /// public ServerMetricsEntity() { RunningTasks = new List(); } + /// + /// The number of days of events able to fit in the memory cache. + /// public double EventStoreDaysCached { get; set; } + + /// + /// The number of events able to fit in the memory cache. + /// public int EventStoreEventsCached { get; set; } + + /// + /// The oldest on-disk extent currently stored. + /// public DateTime? EventStoreFirstExtentRangeStartUtc { get; set; } + + /// + /// The most recent on-disk extent currently stored. + /// public DateTime? EventStoreLastExtentRangeEndUtc { get; set; } + + /// + /// Bytes of free space remaining on the disk used for event storage. + /// public long EventStoreDiskRemainingBytes { get; set; } + /// + /// The number of events that arrived at the ingestion endpoint in the past minute. + /// public int EndpointArrivalsPerMinute { get; set; } + + /// + /// The number of events ingested in the past minute. + /// public int EndpointInfluxPerMinute { get; set; } + + /// + /// The number of bytes of raw JSON event data ingested in the past minute (approximate). + /// public long EndpointIngestedBytesPerMinute { get; set; } + + /// + /// The number of invalid event payloads seen in the past minute. + /// public int EndpointInvalidPayloadsPerMinute { get; set; } + + /// + /// The number of unauthorized event payloads seen in the past minute. + /// public int EndpointUnauthorizedPayloadsPerMinute { get; set; } + /// + /// The length of time for which the Seq server process has been running. + /// public TimeSpan ProcessUptime { get; set; } + + /// + /// The number of bytes working set held by the Seq server process. + /// public long ProcessWorkingSetBytes { get; set; } + + /// + /// The number of threads running in the Seq server process. + /// public int ProcessThreads { get; set; } + + /// + /// The number of thread pool user threads available. + /// public int ProcessThreadPoolUserThreadsAvailable { get; set; } + + /// + /// The number of async I/O thread pool threads available. + /// public int ProcessThreadPoolIocpThreadsAvailable { get; set; } + /// + /// The proportion of system physical memory that is currently allocated. + /// public double SystemMemoryUtilization { get; set; } + /// + /// Tasks running in the Seq server. + /// public List RunningTasks { get; set; } + /// + /// The number of SQL-style queries executed in the past minute. + /// public int QueriesPerMinute { get; set; } + + /// + /// The number of time slices from SQL-style queries that could be read from cache in the past minute. + /// public int QueryCacheTimeSliceHitsPerMinute { get; set; } + + /// + /// The number of cached SQL query time slices invalidated in the past minute. + /// public int QueryCacheInvalidationsPerMinute { get; set; } + /// + /// The number of active sessions reading from or writing to Seq's internal metadata store. + /// public int DocumentStoreActiveSessions { get; set; } } } diff --git a/src/Seq.Api/Model/Diagnostics/ServerStatusPart.cs b/src/Seq.Api/Model/Diagnostics/ServerStatusPart.cs index dc15881..00c3054 100644 --- a/src/Seq.Api/Model/Diagnostics/ServerStatusPart.cs +++ b/src/Seq.Api/Model/Diagnostics/ServerStatusPart.cs @@ -1,7 +1,27 @@ -namespace Seq.Api.Model.Diagnostics +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Diagnostics { + /// + /// Describes the status of the Seq server. + /// public class ServerStatusPart { + /// + /// Individual status messages. + /// public StatusMessagePart[] StatusMessages { get; set; } } } diff --git a/src/Seq.Api/Model/Diagnostics/StatusMessagePart.cs b/src/Seq.Api/Model/Diagnostics/StatusMessagePart.cs index ab6d6af..196ee8e 100644 --- a/src/Seq.Api/Model/Diagnostics/StatusMessagePart.cs +++ b/src/Seq.Api/Model/Diagnostics/StatusMessagePart.cs @@ -1,8 +1,32 @@ -namespace Seq.Api.Model.Diagnostics +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Diagnostics { + /// + /// A status message relating to the Seq server. + /// public class StatusMessagePart { + /// + /// A descriptive level (Information, Warning, or Error). + /// public string Level { get; set; } + + /// + /// The message text. + /// public string Message { get; set; } } } diff --git a/src/Seq.Api/Model/Entity.cs b/src/Seq.Api/Model/Entity.cs index 7d3a98f..9b3e02e 100644 --- a/src/Seq.Api/Model/Entity.cs +++ b/src/Seq.Api/Model/Entity.cs @@ -17,6 +17,9 @@ namespace Seq.Api.Model /// /// A uniquely-identifiable resource available from the Seq HTTP API. /// + /// Entities are the persistent top-level resources that have a stable + /// URI. The API client uses the contrasting suffix *Part to designate + /// resources that are transient or not directly addressable. public abstract class Entity : ILinked { /// diff --git a/src/Seq.Api/Model/Events/DeleteResultPart.cs b/src/Seq.Api/Model/Events/DeleteResultPart.cs index ebab4f2..4c7943d 100644 --- a/src/Seq.Api/Model/Events/DeleteResultPart.cs +++ b/src/Seq.Api/Model/Events/DeleteResultPart.cs @@ -1,5 +1,22 @@ -namespace Seq.Api.Model.Events +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Events { + /// + /// The (empty) result of executing a deletion request. + /// public class DeleteResultPart { } diff --git a/src/Seq.Api/Model/Events/EventEntity.cs b/src/Seq.Api/Model/Events/EventEntity.cs index 6ec41dc..5995066 100644 --- a/src/Seq.Api/Model/Events/EventEntity.cs +++ b/src/Seq.Api/Model/Events/EventEntity.cs @@ -1,21 +1,62 @@ -using System.Collections.Generic; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System.Collections.Generic; using Newtonsoft.Json; namespace Seq.Api.Model.Events { + /// + /// An event. + /// public class EventEntity : Entity { + /// + /// The ISO-8601 timestamp at which the event occurred. + /// public string Timestamp { get; set; } + + /// + /// Properties associated with the event. + /// public List Properties { get; set; } + + /// + /// Pre-parsed tokens showing how the event's message is constructed from its properties. + /// public List MessageTemplateTokens { get; set; } + + /// + /// A string describing the event's type, in dollar-prefixed hexadecimal; e.g. $c0ffee00. + /// public string EventType { get; set; } + /// + /// A level associated with an event; null may indicate that the event is informational. + /// [JsonProperty(NullValueHandling = NullValueHandling.Ignore)] public string Level { get; set; } + /// + /// An exception, stack trace/backtrace associated with the event. + /// [JsonProperty(NullValueHandling = NullValueHandling.Ignore)] public string Exception { get; set; } + /// + /// If requested, a pre-rendered version of the templated event message. + /// [JsonProperty(NullValueHandling = NullValueHandling.Ignore)] public string RenderedMessage { get; set; } } diff --git a/src/Seq.Api/Model/Events/EventInputResultPart.cs b/src/Seq.Api/Model/Events/EventInputResultPart.cs index dfd600d..07ec1f6 100644 --- a/src/Seq.Api/Model/Events/EventInputResultPart.cs +++ b/src/Seq.Api/Model/Events/EventInputResultPart.cs @@ -1,9 +1,30 @@ -using Seq.Api.Model.LogEvents; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using Seq.Api.Model.LogEvents; namespace Seq.Api.Model.Events { + /// + /// The information returned from ingesting a batch of events. + /// public class EventInputResultPart { + /// + /// The minimum level at which events will be accepted by the + /// server. + /// public LogEventLevel? MinimumLevelAccepted { get; set; } } } diff --git a/src/Seq.Api/Model/Events/EventPropertyPart.cs b/src/Seq.Api/Model/Events/EventPropertyPart.cs index 547cb50..006ce1e 100644 --- a/src/Seq.Api/Model/Events/EventPropertyPart.cs +++ b/src/Seq.Api/Model/Events/EventPropertyPart.cs @@ -1,17 +1,46 @@ +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + using System; namespace Seq.Api.Model.Events { + /// + /// A name/value property associated with an event. + /// + // Note, this duplicates InputAppliedPropertyPart. public class EventPropertyPart { + /// + /// Construct an . + /// + /// The property name (required). + /// The property value, or null. public EventPropertyPart(string name, object value) { - if (name == null) throw new ArgumentNullException(nameof(name)); - Name = name; + Name = name ?? throw new ArgumentNullException(nameof(name)); Value = value; } - public string Name { get; private set; } - public object Value { get; private set; } + /// + /// The property name (required). + /// + public string Name { get; } + + /// + /// The property value, or null. + /// + public object Value { get; } } } diff --git a/src/Seq.Api/Model/Events/MessageTemplateTokenPart.cs b/src/Seq.Api/Model/Events/MessageTemplateTokenPart.cs index 9fc19fc..a691e52 100644 --- a/src/Seq.Api/Model/Events/MessageTemplateTokenPart.cs +++ b/src/Seq.Api/Model/Events/MessageTemplateTokenPart.cs @@ -1,18 +1,47 @@ +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + using Newtonsoft.Json; namespace Seq.Api.Model.Events { + /// + /// A token parsed from a message template. + /// public class MessageTemplateTokenPart { + /// + /// Plain text, if the token is a text token. + /// [JsonProperty(NullValueHandling = NullValueHandling.Ignore)] public string Text { get; set; } - // or + + /// + /// The name of the property to be rendered in place of the token, if a property token. + /// [JsonProperty(NullValueHandling = NullValueHandling.Ignore)] public string PropertyName { get; set; } + /// + /// The raw source text from the message template (provided for both text and property tokens). + /// [JsonProperty(NullValueHandling = NullValueHandling.Ignore)] public string RawText { get; set; } + /// + /// A pre-formatted value, if the token carries language-specific formatting directives. + /// [JsonProperty(NullValueHandling = NullValueHandling.Ignore)] public string FormattedValue { get; set; } } diff --git a/src/Seq.Api/Model/Events/ResultSetPart.cs b/src/Seq.Api/Model/Events/ResultSetPart.cs index d50a413..c900a15 100644 --- a/src/Seq.Api/Model/Events/ResultSetPart.cs +++ b/src/Seq.Api/Model/Events/ResultSetPart.cs @@ -1,11 +1,36 @@ -using System.Collections.Generic; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System.Collections.Generic; using Seq.Api.Model.Shared; namespace Seq.Api.Model.Events { + /// + /// The result of a request for events matching a filter or signal. + /// public class ResultSetPart { + /// + /// Matching events. + /// public List Events { get; set; } + + /// + /// Statistics describing the server resources used to construct the + /// result set. + /// public StatisticsPart Statistics { get; set; } } } diff --git a/src/Seq.Api/Model/Expressions/ExpressionPart.cs b/src/Seq.Api/Model/Expressions/ExpressionPart.cs index d8cbddf..5362840 100644 --- a/src/Seq.Api/Model/Expressions/ExpressionPart.cs +++ b/src/Seq.Api/Model/Expressions/ExpressionPart.cs @@ -1,9 +1,38 @@ -namespace Seq.Api.Model.Expressions +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Expressions { + /// + /// Information about a filter expression. + /// public class ExpressionPart { + /// + /// The expression in strict syntax. + /// public string StrictExpression { get; set; } + + /// + /// Whether the expression was considered to be a free text search. + /// public bool MatchedAsText { get; set; } + + /// + /// If is true, the reason that the + /// expression was not considered a valid structured expression. + /// public string ReasonIfMatchedAsText { get; set; } } } diff --git a/src/Seq.Api/Model/Expressions/SqlExpressionPart.cs b/src/Seq.Api/Model/Expressions/SqlExpressionPart.cs index 21ac587..e7650e6 100644 --- a/src/Seq.Api/Model/Expressions/SqlExpressionPart.cs +++ b/src/Seq.Api/Model/Expressions/SqlExpressionPart.cs @@ -1,7 +1,27 @@ -namespace Seq.Api.Model.Expressions +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Expressions { + /// + /// Describes an expression in strict SQL-style syntax. + /// public class SqlExpressionPart { + /// + /// The expression in SQL-style syntax. + /// public string Expression { get; set; } } } \ No newline at end of file diff --git a/src/Seq.Api/Model/Feeds/NuGetFeedEntity.cs b/src/Seq.Api/Model/Feeds/NuGetFeedEntity.cs index ae653dc..bb318f0 100644 --- a/src/Seq.Api/Model/Feeds/NuGetFeedEntity.cs +++ b/src/Seq.Api/Model/Feeds/NuGetFeedEntity.cs @@ -1,10 +1,43 @@ -namespace Seq.Api.Model.Feeds +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Feeds { - public class NuGetFeedEntity : Seq.Api.Model.Entity + /// + /// A NuGet feed. + /// + public class NuGetFeedEntity : Entity { + /// + /// The feed name. + /// public string Name { get; set; } + + /// + /// A URI or folder path at which the feed is located. + /// public string Location { get; set; } + + /// + /// If required, a username that will be sent when accessing the feed. + /// public string Username { get; set; } + + /// + /// When is non-empty, can be used to set an associated + /// password. + /// public string NewPassword { get; set; } } } diff --git a/src/Seq.Api/Model/Inputs/ApiKeyEntity.cs b/src/Seq.Api/Model/Inputs/ApiKeyEntity.cs index 058ffd3..9cc7300 100644 --- a/src/Seq.Api/Model/Inputs/ApiKeyEntity.cs +++ b/src/Seq.Api/Model/Inputs/ApiKeyEntity.cs @@ -1,4 +1,18 @@ -using System.Collections.Generic; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System.Collections.Generic; using Newtonsoft.Json; using Seq.Api.Model.LogEvents; using Seq.Api.Model.Security; @@ -6,19 +20,75 @@ namespace Seq.Api.Model.Inputs { + /// + /// API keys can be used to authenticate and identify log event sources, and for + /// users to delegate some or all permissions to a client of the Seq API (app or integration) without exposing + /// user credentials. + /// public class ApiKeyEntity : Entity { + /// + /// A friendly human-readable description of the API key. + /// public string Title { get; set; } + + /// + /// The API key token. API keys generated for versions of Seq prior to 5.0 will expose this value. From 5.0 onwards, + /// can be specified explicitly when creating an API key, but is not readable once the API key is created. + /// Leaving the token blank will cause the server to generate a cryptographically random API key token. After creation, the first + /// few characters of the token will be readable from , but because only a cryptographically-secure + /// hash of the token is stored internally, the token itself cannot be retrieved. + /// public string Token { get; set; } + + /// + /// A few characters from the start of the stored as plain text, to aid in identifying tokens. + /// public string TokenPrefix { get; set; } + + /// + /// Properties that will be automatically added to all events ingested using the key. These will override any properties with + /// the same names already present on the event. + /// public List AppliedProperties { get; set; } = new List(); + + /// + /// A filter that selects events to ingest. If null, all events received using the key will be ingested. + /// public SignalFilterPart InputFilter { get; set; } = new SignalFilterPart(); + + /// + /// A minimum level at which events received using the key will be ingested. The level hierarchy understood by Seq is fuzzy + /// enough to handle most common leveling schemes. This value will be provided to callers so that they can dynamically + /// filter events client-side, if supported. + /// public LogEventLevel? MinimumLevel { get; set; } + + /// + /// If true, timestamps already present on the events will be ignored, and server timestamps used instead. This is not + /// recommended for most use cases. + /// public bool UseServerTimestamps { get; set; } + + /// + /// If true, the key is the built-in (tokenless) API key. + /// public bool IsDefault { get; set; } + + /// + /// If non-null, the id of the user for whom this is a personal API key. + /// public string OwnerId { get; set; } + + /// + /// The s assigned to the API key. Note that, if the API key is owned by an individual user, permissions + /// not held by the user will be ignored by the server. + /// public HashSet AssignedPermissions { get; set; } = new HashSet(); + /// + /// Information about the ingestion activity using this API key. + /// [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)] public ApiKeyMetricsPart Metrics { get; set; } = new ApiKeyMetricsPart(); } diff --git a/src/Seq.Api/Model/Inputs/ApiKeyMetricsPart.cs b/src/Seq.Api/Model/Inputs/ApiKeyMetricsPart.cs index 5ac3870..d68ec35 100644 --- a/src/Seq.Api/Model/Inputs/ApiKeyMetricsPart.cs +++ b/src/Seq.Api/Model/Inputs/ApiKeyMetricsPart.cs @@ -1,9 +1,40 @@ -namespace Seq.Api.Model.Inputs +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Inputs { + /// + /// Information about ingestion activity using an API key. + /// public class ApiKeyMetricsPart { + /// + /// The number of events that arrived at the server tagged with this + /// key in the past minute. + /// public int ArrivalsPerMinute { get; set; } + + /// + /// The number of events that ingested by the server tagged with this + /// key in the past minute. + /// public int InfluxPerMinute { get; set; } + + /// + /// The raw JSON bytes (approximate) tagged with this API key that were ingested + /// by the server in the past minute. + /// public long IngestedBytesPerMinute { get; set; } } } \ No newline at end of file diff --git a/src/Seq.Api/Model/Inputs/InputAppliedPropertyPart.cs b/src/Seq.Api/Model/Inputs/InputAppliedPropertyPart.cs index d951ff7..3a6fb3d 100644 --- a/src/Seq.Api/Model/Inputs/InputAppliedPropertyPart.cs +++ b/src/Seq.Api/Model/Inputs/InputAppliedPropertyPart.cs @@ -1,8 +1,33 @@ -namespace Seq.Api.Model.Inputs +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Inputs { + /// + /// A name/value property attached to events ingested through an API key. + /// + // Note, this duplicates EventPropertyPart. public class InputAppliedPropertyPart { + /// + /// The property name (required). + /// public string Name { get; set; } + + /// + /// The property value, or null. + /// public object Value { get; set; } } } \ No newline at end of file diff --git a/src/Seq.Api/Model/License/LicenseEntity.cs b/src/Seq.Api/Model/License/LicenseEntity.cs index c610991..f03d3ca 100644 --- a/src/Seq.Api/Model/License/LicenseEntity.cs +++ b/src/Seq.Api/Model/License/LicenseEntity.cs @@ -1,13 +1,60 @@ -namespace Seq.Api.Model.License +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.License { + /// + /// A Seq license certificate. + /// public class LicenseEntity : Entity { + /// + /// The cryptographically-signed certificate that describes the + /// license, or null if the server is using the default license. + /// public string LicenseText { get; set; } + + /// + /// Whether or not the license is valid for the server. + /// public bool IsValid { get; set; } + + /// + /// If true, the server is using the default license which allows + /// a single person to access the Seq server. + /// public bool IsSingleUser { get; set; } + + /// + /// Information about the status of the license. + /// public string StatusDescription { get; set; } + + /// + /// If true, see for important information. + /// public bool IsWarning { get; set; } + + /// + /// If true, the license can be renewed online. + /// public bool CanRenewOnlineNow { get; set; } + + /// + /// The number of users licensed to access the Seq server, or null if + /// the license has no user limit. + /// public int? LicensedUsers { get; set; } } } diff --git a/src/Seq.Api/Model/LinkCollection.cs b/src/Seq.Api/Model/LinkCollection.cs index aebab05..27fc505 100644 --- a/src/Seq.Api/Model/LinkCollection.cs +++ b/src/Seq.Api/Model/LinkCollection.cs @@ -25,6 +25,9 @@ namespace Seq.Api.Model [JsonConverter(typeof(LinkCollectionConverter))] public class LinkCollection : Dictionary { + /// + /// Construct a . + /// public LinkCollection() : base(StringComparer.OrdinalIgnoreCase) { } } } diff --git a/src/Seq.Api/Model/LogEvents/LogEventLevel.cs b/src/Seq.Api/Model/LogEvents/LogEventLevel.cs index eb77609..dde7281 100644 --- a/src/Seq.Api/Model/LogEvents/LogEventLevel.cs +++ b/src/Seq.Api/Model/LogEvents/LogEventLevel.cs @@ -1,4 +1,18 @@ -namespace Seq.Api.Model.LogEvents +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.LogEvents { /// /// Specifies the meaning and relative importance of a log event. diff --git a/src/Seq.Api/Model/Monitoring/AlertPart.cs b/src/Seq.Api/Model/Monitoring/AlertPart.cs index cb3a9fe..d9b10a7 100644 --- a/src/Seq.Api/Model/Monitoring/AlertPart.cs +++ b/src/Seq.Api/Model/Monitoring/AlertPart.cs @@ -1,22 +1,78 @@ -using Seq.Api.Model.LogEvents; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using Seq.Api.Model.LogEvents; using System; using System.Collections.Generic; +using Seq.Api.Model.AppInstances; namespace Seq.Api.Model.Monitoring { + /// + /// An alert attached to a dashboard chart. + /// public class AlertPart { Dictionary _notificationAppSettingOverrides = new Dictionary(); + /// + /// The unique id assigned to the alert. + /// public string Id { get; set; } + + /// + /// The alert condition. This is effectively a having clause over the grouped results + /// computed by the . + /// public string Condition { get; set; } + + /// + /// A friendly, human-readable description of the alert. + /// public string Title { get; set; } + + /// + /// The interval within which the alert condition will be measured. + /// public TimeSpan MeasurementWindow { get; set; } + + /// + /// The time allowed for events to reach the server before being included in alert calculations. + /// This is relative to the current server clock. + /// public TimeSpan StabilizationWindow { get; set; } = TimeSpan.FromSeconds(30); + + /// + /// The time after the alert files within which no further notifications will be sent for the + /// alert. + /// public TimeSpan SuppressionTime { get; set; } + + /// + /// An informational level that suggests the importance of the alert. + /// public LogEventLevel Level { get; set; } = LogEventLevel.Warning; + + /// + /// The id of an that will receive notifications from the alert. + /// public string NotificationAppInstanceId { get; set; } + /// + /// Additional properties that will be used to configure the notification app when triggered + /// by the alert. + /// public Dictionary NotificationAppSettingOverrides { get => _notificationAppSettingOverrides; diff --git a/src/Seq.Api/Model/Monitoring/ChartDisplayStylePart.cs b/src/Seq.Api/Model/Monitoring/ChartDisplayStylePart.cs index 16729e1..32af9b0 100644 --- a/src/Seq.Api/Model/Monitoring/ChartDisplayStylePart.cs +++ b/src/Seq.Api/Model/Monitoring/ChartDisplayStylePart.cs @@ -1,8 +1,32 @@ -namespace Seq.Api.Model.Monitoring +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Monitoring { + /// + /// How a chart will be displayed on a dashboard. + /// public class ChartDisplayStylePart { + /// + /// The width of the chart, in 1/12th columns. + /// public int WidthColumns { get; set; } = 6; + + /// + /// The height of the chart, in rows. + /// public int HeightRows { get; set; } = 1; } } diff --git a/src/Seq.Api/Model/Monitoring/ChartPart.cs b/src/Seq.Api/Model/Monitoring/ChartPart.cs index 3b6be33..196a11c 100644 --- a/src/Seq.Api/Model/Monitoring/ChartPart.cs +++ b/src/Seq.Api/Model/Monitoring/ChartPart.cs @@ -1,14 +1,51 @@ -using System.Collections.Generic; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System.Collections.Generic; using Seq.Api.Model.Signals; namespace Seq.Api.Model.Monitoring { + /// + /// A chart that appears on a dashboard. + /// public class ChartPart { + /// + /// The unique id assigned to the chart. + /// public string Id { get; set; } + + /// + /// A human-friendly title for the chart. + /// public string Title { get; set; } + + /// + /// An optional that limits what data the chart will display. + /// public SignalExpressionPart SignalExpression { get; set; } + + /// + /// The individual queries making up the chart. In most instances, only one query is currently supported + /// here. + /// public List Queries { get; set; } = new List(); + + /// + /// How the chart will appear on the dashboard. + /// public ChartDisplayStylePart DisplayStyle { get; set; } = new ChartDisplayStylePart(); } } diff --git a/src/Seq.Api/Model/Monitoring/ChartQueryPart.cs b/src/Seq.Api/Model/Monitoring/ChartQueryPart.cs index fa5a53a..d2562bb 100644 --- a/src/Seq.Api/Model/Monitoring/ChartQueryPart.cs +++ b/src/Seq.Api/Model/Monitoring/ChartQueryPart.cs @@ -1,19 +1,75 @@ -using System.Collections.Generic; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System.Collections.Generic; using Seq.Api.Model.Signals; namespace Seq.Api.Model.Monitoring { + /// + /// A query within a chart. + /// public class ChartQueryPart { + /// + /// The unique id assigned to the query. + /// public string Id { get; set; } + + /// + /// Individual measurements included in the query. These are effectively projected columns. + /// public List Measurements { get; set; } = new List(); + + /// + /// An optional filtering where clause limiting the data that contributes to the chart. + /// public string Where { get; set; } + + /// + /// An optional limiting the data that contributes to the chart. + /// public SignalExpressionPart SignalExpression { get; set; } + + /// + /// A series of expressions used to group data returned by the query. + /// public List GroupBy { get; set; } = new List(); + + /// + /// How measurements included in the chart will be displayed. + /// public MeasurementDisplayStylePart DisplayStyle { get; set; } = new MeasurementDisplayStylePart(); + + /// + /// Alerts attached to the chart. + /// public List Alerts { get; set; } = new List(); + + /// + /// A filter that limits which groups will be displayed on the chart. Not supported by all chart types. + /// public string Having { get; set; } + + /// + /// An ordering applied to the results of the query; not supported by all chart types. + /// public List OrderBy { get; set; } = new List(); + + /// + /// The row limit used for the query. By default, a server-determined limit will be applied. + /// public int? Limit { get; set; } } } diff --git a/src/Seq.Api/Model/Monitoring/DashboardEntity.cs b/src/Seq.Api/Model/Monitoring/DashboardEntity.cs index 0e932ea..ba6f91a 100644 --- a/src/Seq.Api/Model/Monitoring/DashboardEntity.cs +++ b/src/Seq.Api/Model/Monitoring/DashboardEntity.cs @@ -1,18 +1,51 @@ -using System.Collections.Generic; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System.Collections.Generic; +using Seq.Api.Model.Security; using Seq.Api.Model.Signals; namespace Seq.Api.Model.Monitoring { + /// + /// A dashboard. + /// public class DashboardEntity : Entity { + /// + /// The user who owns the dashboard. If null, the dashboard is shared. + /// public string OwnerId { get; set; } + /// + /// The friendly, human-readable title for the dashboard. + /// public string Title { get; set; } + /// + /// If true, only users with can modify the dashboard. + /// public bool IsProtected { get; set; } + /// + /// An optional that limits the data contributing to the dashboard. + /// public SignalExpressionPart SignalExpression { get; set; } + /// + /// The list of charts included in the dashboard. + /// public List Charts { get; set; } = new List(); } } diff --git a/src/Seq.Api/Model/Monitoring/MeasurementDisplayPalette.cs b/src/Seq.Api/Model/Monitoring/MeasurementDisplayPalette.cs index 2206eb8..8b16577 100644 --- a/src/Seq.Api/Model/Monitoring/MeasurementDisplayPalette.cs +++ b/src/Seq.Api/Model/Monitoring/MeasurementDisplayPalette.cs @@ -1,11 +1,47 @@ -namespace Seq.Api.Model.Monitoring +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Monitoring { + /// + /// The color palette used for displaying a measurement on a chart. + /// public enum MeasurementDisplayPalette { + /// + /// The default palette. + /// Default, + + /// + /// A predominantly red palette. + /// Reds, + + /// + /// A predominantly green palette. + /// Greens, + + /// + /// A predominantly blue palette. + /// Blues, + + /// + /// An orange/purple palette. + /// OrangePurple } } diff --git a/src/Seq.Api/Model/Monitoring/MeasurementDisplayStylePart.cs b/src/Seq.Api/Model/Monitoring/MeasurementDisplayStylePart.cs index 75209f4..9f22f40 100644 --- a/src/Seq.Api/Model/Monitoring/MeasurementDisplayStylePart.cs +++ b/src/Seq.Api/Model/Monitoring/MeasurementDisplayStylePart.cs @@ -1,12 +1,52 @@ -namespace Seq.Api.Model.Monitoring +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Monitoring { + /// + /// How a measurement will be displayed within a chart. + /// public class MeasurementDisplayStylePart { + /// + /// The type of display used for the measurement. + /// public MeasurementDisplayType Type { get; set; } = MeasurementDisplayType.Line; + + /// + /// For line chart measurement display types, whether the area under the line will be filled. + /// public bool LineFillToZeroY { get; set; } + + /// + /// For line chart measurement display types, whether the points along the line will be visibly marked. + /// public bool LineShowMarkers { get; set; } = true; + + /// + /// For bar chart measurement display types, whether the sum of all bars will be shown as an overlay. + /// public bool BarOverlaySum { get; set; } + + /// + /// For measurement display types that include a legend, whether the legend will be shown. + /// public bool SuppressLegend { get; set; } + + /// + /// The color palette used to display the chart. + /// public MeasurementDisplayPalette Palette { get; set; } = MeasurementDisplayPalette.Default; } } diff --git a/src/Seq.Api/Model/Monitoring/MeasurementDisplayType.cs b/src/Seq.Api/Model/Monitoring/MeasurementDisplayType.cs index ed40ae9..c1f28cc 100644 --- a/src/Seq.Api/Model/Monitoring/MeasurementDisplayType.cs +++ b/src/Seq.Api/Model/Monitoring/MeasurementDisplayType.cs @@ -1,12 +1,52 @@ -namespace Seq.Api.Model.Monitoring +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Monitoring { + /// + /// The method used to visually represent a measurement. + /// public enum MeasurementDisplayType { + /// + /// A line chart. Requires the measurement and query to include a time axis. + /// Line, + + /// + /// A bar chart. + /// Bar, + + /// + /// A point (scatter) chart. + /// Point, + + /// + /// A single textual value. Requires that the measurement and query produce a single value. + /// Value, + + /// + /// A (donut-styled) pie chart. + /// Pie, + + /// + /// A table of raw data values. + /// Table } } diff --git a/src/Seq.Api/Model/Monitoring/MeasurementPart.cs b/src/Seq.Api/Model/Monitoring/MeasurementPart.cs index c6dfcf6..b43f863 100644 --- a/src/Seq.Api/Model/Monitoring/MeasurementPart.cs +++ b/src/Seq.Api/Model/Monitoring/MeasurementPart.cs @@ -1,8 +1,32 @@ -namespace Seq.Api.Model.Monitoring +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Monitoring { + /// + /// A measurement that contributes to a chart. + /// public class MeasurementPart { + /// + /// The expression (selected column) that computes the value of the measurement. + /// public string Value { get; set; } + + /// + /// An optional label for the measurement (effectively the right-hand size of an as clause). + /// public string Label { get; set; } } } diff --git a/src/Seq.Api/Model/Permalinks/PermalinkEntity.cs b/src/Seq.Api/Model/Permalinks/PermalinkEntity.cs index 4111112..539e0fe 100644 --- a/src/Seq.Api/Model/Permalinks/PermalinkEntity.cs +++ b/src/Seq.Api/Model/Permalinks/PermalinkEntity.cs @@ -1,21 +1,54 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; using Newtonsoft.Json; using Seq.Api.Model.Events; +using Seq.Api.ResourceGroups; namespace Seq.Api.Model.Permalinks { + /// + /// A permanently preserved event with a stable URI. + /// public class PermalinkEntity : Entity { /// - /// When retrieving an event that _may_ be permalinked (backwards compatibility), - /// this hint is given by specifiying `permalinkId=unknown` in the API call. + /// When retrieving an event that may be permalinked (backwards compatibility), + /// this hint is given by specifying `permalinkId=unknown` in the API call. /// public const string UnknownId = "unknown"; + /// + /// The owner of the permalink. + /// public string OwnerId { get; set; } + + /// + /// The original id of the permalinked event. + /// public string EventId { get; set; } + + /// + /// When the permalink was created. + /// public DateTime CreatedUtc { get; set; } + /// + /// The event itself. Only populated when explicitly requested from the API. + /// See . + /// [JsonProperty(NullValueHandling = NullValueHandling.Ignore)] public EventEntity Event { get; set; } } diff --git a/src/Seq.Api/Model/Retention/RetentionPolicyEntity.cs b/src/Seq.Api/Model/Retention/RetentionPolicyEntity.cs index 09f4a2b..451460b 100644 --- a/src/Seq.Api/Model/Retention/RetentionPolicyEntity.cs +++ b/src/Seq.Api/Model/Retention/RetentionPolicyEntity.cs @@ -1,14 +1,43 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; using Seq.Api.Model.Signals; namespace Seq.Api.Model.Retention { + /// + /// A retention policy. Identifies a subset of events to delete at a specified age. + /// public class RetentionPolicyEntity : Entity { + /// + /// The age at which events will be deleted by the policy. This is based on the + /// events' timestamps relative to the server's clock. + /// public TimeSpan RetentionTime { get; set; } + /// + /// An optional describing the set of events + /// to delete. If null, the policy will efficiently truncate the event store, + /// deleting all events. + /// public SignalExpressionPart RemovedSignalExpression { get; set; } + /// + /// Obsolete. + /// [Obsolete("Replaced by RemovedSignalExpression.")] public string SignalId { get; set; } } diff --git a/src/Seq.Api/Model/Root/RootEntity.cs b/src/Seq.Api/Model/Root/RootEntity.cs index 7f2877a..f529f3b 100644 --- a/src/Seq.Api/Model/Root/RootEntity.cs +++ b/src/Seq.Api/Model/Root/RootEntity.cs @@ -1,15 +1,50 @@ -namespace Seq.Api.Model.Root +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Root { + /// + /// Information about the API exposed by the server. + /// public class RootEntity : ILinked { + /// + /// Construct a . + /// public RootEntity() { Links = new LinkCollection(); } + /// + /// The product serving the API. + /// public string Product { get; set; } + + /// + /// The version of the product serving the API. + /// public string Version { get; set; } + + /// + /// An informational name identifying the instance. + /// public string InstanceName { get; set; } + + /// + /// Links to resources exposed by the API. + /// public LinkCollection Links { get; set; } } } diff --git a/src/Seq.Api/Model/Security/Permission.cs b/src/Seq.Api/Model/Security/Permission.cs index 88486a0..0ef450c 100644 --- a/src/Seq.Api/Model/Security/Permission.cs +++ b/src/Seq.Api/Model/Security/Permission.cs @@ -1,4 +1,18 @@ -namespace Seq.Api.Model.Security +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Security { /// /// A permission is an access right 1) held by a principal, and 2) demanded by an endpoint. Permissions diff --git a/src/Seq.Api/Model/Security/RoleEntity.cs b/src/Seq.Api/Model/Security/RoleEntity.cs index 2d88ce2..c44748c 100644 --- a/src/Seq.Api/Model/Security/RoleEntity.cs +++ b/src/Seq.Api/Model/Security/RoleEntity.cs @@ -1,10 +1,34 @@ -using System.Collections.Generic; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System.Collections.Generic; namespace Seq.Api.Model.Security { + /// + /// A role is a set of permissions designed to support a particular type of user. + /// public class RoleEntity : Entity { + /// + /// The name of the role. + /// public string Title { get; set; } + + /// + /// Permissions granted to users in the role. + /// public HashSet Permissions { get; set; } = new HashSet(); } } diff --git a/src/Seq.Api/Model/Security/WellKnownRole.cs b/src/Seq.Api/Model/Security/WellKnownRole.cs index 19678c6..4a05e5c 100644 --- a/src/Seq.Api/Model/Security/WellKnownRole.cs +++ b/src/Seq.Api/Model/Security/WellKnownRole.cs @@ -1,8 +1,35 @@ -namespace Seq.Api.Model.Security +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; + +namespace Seq.Api.Model.Security { + /// + /// Obsolete. + /// + [Obsolete("It's recommended that new code look up roles by name in `SeqConnection.Roles`.")] public static class WellKnownRole { + /// + /// Obsolete. + /// public const string AdministratorRoleId = "role-administrator"; + + /// + /// Obsolete. + /// public const string UserRoleId = "role-user"; } } diff --git a/src/Seq.Api/Model/Settings/InternalErrorReportingSettingsPart.cs b/src/Seq.Api/Model/Settings/InternalErrorReportingSettingsPart.cs index deaf7bf..cee8bd9 100644 --- a/src/Seq.Api/Model/Settings/InternalErrorReportingSettingsPart.cs +++ b/src/Seq.Api/Model/Settings/InternalErrorReportingSettingsPart.cs @@ -1,8 +1,35 @@ -namespace Seq.Api.Model.Settings +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Settings { + /// + /// Settings for internal error reporting. + /// public class InternalErrorReportingSettingsPart { + /// + /// If true, redacted internal error reports will be sent + /// automatically to Datalust. + /// public bool InternalErrorReportingEnabled { get; set; } + + /// + /// If internal error reporting is enabled, an optional email address + /// that will be attached to error reports so that the support team + /// at Datalust can respond with fix/mitigation information. + /// public string ReplyEmail { get; set; } } } diff --git a/src/Seq.Api/Model/Settings/SettingEntity.cs b/src/Seq.Api/Model/Settings/SettingEntity.cs index 9f4c5d5..9b35481 100644 --- a/src/Seq.Api/Model/Settings/SettingEntity.cs +++ b/src/Seq.Api/Model/Settings/SettingEntity.cs @@ -1,8 +1,35 @@ -namespace Seq.Api.Model.Settings +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Settings { + /// + /// A Seq system-level setting. Note that only runtime-modifiable + /// settings are exposed this way. Other configuration options are + /// set using the Seq server command-line. + /// public class SettingEntity : Entity { + /// + /// The name of the setting. See for a selection + /// of current values. + /// public string Name { get; set; } + + /// + /// The value of the setting. + /// public object Value { get; set; } } } diff --git a/src/Seq.Api/Model/Settings/SettingName.cs b/src/Seq.Api/Model/Settings/SettingName.cs index f9ab369..955684f 100644 --- a/src/Seq.Api/Model/Settings/SettingName.cs +++ b/src/Seq.Api/Model/Settings/SettingName.cs @@ -1,29 +1,152 @@ -namespace Seq.Api.Model.Settings +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using Seq.Api.Model.Apps; +using Seq.Api.Model.Updates; +using Seq.Api.ResourceGroups; + +namespace Seq.Api.Model.Settings { + /// + /// Runtime-modifiable setting names. See also and + /// . + /// public enum SettingName { + /// + /// The name of an Active Directory group within which users will be automatically + /// be granted user access to Seq. + /// AutomaticAccessADGroup, + + /// + /// If true, Azure Active Directory accounts in the configured tenant will + /// be automatically granted user access to Seq. + /// AutomaticallyGrantUserAccessToADAccounts, + + /// + /// The Azure Active Directory client id. + /// AzureADClientId, + + /// + /// The Azure Active Directory client key. + /// AzureADClientKey, + + /// + /// The Azure Active Directory tenant id. + /// AzureADTenantId, + + /// + /// Server-local filesystem location where automatic backups are stored. + /// BackupLocation, + + /// + /// The number of backups to keep. + /// BackupsToKeep, + + /// + /// The UTC time of day to record new backups. + /// BackupUtcTimeOfDay, + + /// + /// If true, Seq will periodically check configured NuGet feed for + /// updated versions of installed app packages, and + /// set accordingly. + /// CheckForPackageUpdates, + + /// + /// If true, Seq will periodically check for new Seq versions, and + /// create an accordingly. + /// CheckForUpdates, + + /// + /// A friendly, public, human-readable title identifying this particular Seq instance. + /// InstanceTitle, + + /// + /// If true, the server supports Active Directory authentication. + /// IsActiveDirectoryAuthentication, + + /// + /// If true, the server has authentication enabled. + /// IsAuthenticationEnabled, + + /// + /// Obsolete. + /// LazilyFlushEventWrites, + + /// + /// Tracks whether an admin user has dismissed the master key backup warning. + /// MasterKeyIsBackedUp, + + /// + /// The minimum storage space, in bytes, on the disk containing log events, before + /// Seq will stop accepting new events. + /// MinimumFreeStorageSpace, + + /// + /// A comma-separated list of (shared) signal ids that will be included in any new user's + /// personal default workspace. + /// NewUserShowSignalIds, + + /// + /// A comma-separated list of (shared) SQL query ids that will be included in any new user's + /// personal default workspace. + /// NewUserShowQueryIds, + + /// + /// A comma-separated list of (shared) dashboard ids that will be included in any new user's + /// personal default workspace. + /// NewUserShowDashboardIds, + + /// + /// If true, ingestion requests incoming via HTTP must be authenticated using an API key or + /// logged-in user session. Only effective when is true. + /// RequireApiKeyForWritingEvents, + + /// + /// The maximum size, in bytes of UTF-8-encoded JSON, beyond which individual events will be rejected. + /// RawEventMaximumContentLength, + + /// + /// The maximum size, in HTTP request content bytes, beyond which ingestion requests will be rejected. + /// RawPayloadMaximumContentLength, + + /// + /// A snippet of CSS that will be included in the front-end's user interface styles. + /// ThemeStyles } } diff --git a/src/Seq.Api/Model/Shared/DeferredRequestEntity.cs b/src/Seq.Api/Model/Shared/DeferredRequestEntity.cs index c98d482..517b19a 100644 --- a/src/Seq.Api/Model/Shared/DeferredRequestEntity.cs +++ b/src/Seq.Api/Model/Shared/DeferredRequestEntity.cs @@ -1,5 +1,23 @@ -namespace Seq.Api.Model.Shared +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Shared { + /// + /// An entity representing a request that will be executed as a long-running (background) task. + /// Includes a link where the result of the request can be accessed. + /// public class DeferredRequestEntity : Entity { } diff --git a/src/Seq.Api/Model/Shared/ErrorPart.cs b/src/Seq.Api/Model/Shared/ErrorPart.cs index b16328f..fca82e2 100644 --- a/src/Seq.Api/Model/Shared/ErrorPart.cs +++ b/src/Seq.Api/Model/Shared/ErrorPart.cs @@ -1,7 +1,27 @@ -namespace Seq.Api.Model.Shared +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Shared { + /// + /// An error returned from the API. + /// public class ErrorPart { + /// + /// The error message. + /// public string Error { get; set; } } } diff --git a/src/Seq.Api/Model/Shared/ResultSetStatus.cs b/src/Seq.Api/Model/Shared/ResultSetStatus.cs index c9d0688..dcd375d 100644 --- a/src/Seq.Api/Model/Shared/ResultSetStatus.cs +++ b/src/Seq.Api/Model/Shared/ResultSetStatus.cs @@ -1,16 +1,42 @@ -namespace Seq.Api.Model.Shared +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Shared { + /// + /// Information about the state of an event result set. + /// public enum ResultSetStatus { + /// + /// Uninitialized value. + /// Unknown, - // Still more to come, scanned as far as requested/short circuit + /// + /// Still more to search (even if this result set is empty). + /// Partial, - // Have covered the whole range + /// + /// Covers the whole range. + /// Complete, - // You asked for 10, I got you 10 + /// + /// Retrieved the requested event count, then stopped. + /// Full } } diff --git a/src/Seq.Api/Model/Shared/StatisticsPart.cs b/src/Seq.Api/Model/Shared/StatisticsPart.cs index 4a5cbed..c66140d 100644 --- a/src/Seq.Api/Model/Shared/StatisticsPart.cs +++ b/src/Seq.Api/Model/Shared/StatisticsPart.cs @@ -1,14 +1,55 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; namespace Seq.Api.Model.Shared { + /// + /// Information about a request to search for events. + /// public class StatisticsPart { + /// + /// The server-side elapsed time taken satisfying the request. + /// public TimeSpan Elapsed { get; set; } + + /// + /// The number of events that were scanned in the search (and were not + /// able to be excluded based on index information or pre-filtering). + /// public long ScannedEventCount { get; set; } + + /// + /// The id of the last event inspected in the search. + /// public string LastReadEventId { get; set; } + + /// + /// The timestamp of the last event inspected in the search. + /// public string LastReadEventTimestamp { get; set; } + + /// + /// Status of the result set. + /// public ResultSetStatus Status { get; set; } + + /// + /// Whether it was necessary to read from disk in processing this request. + /// public bool UncachedSegmentsScanned { get; set; } } } diff --git a/src/Seq.Api/Model/Signals/SignalEntity.cs b/src/Seq.Api/Model/Signals/SignalEntity.cs index cab6ddd..c45d02d 100644 --- a/src/Seq.Api/Model/Signals/SignalEntity.cs +++ b/src/Seq.Api/Model/Signals/SignalEntity.cs @@ -1,11 +1,32 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; using System.Collections.Generic; using Newtonsoft.Json; +using Seq.Api.Model.Security; namespace Seq.Api.Model.Signals { + /// + /// A signal is a collection of filters that identifies a subset of the event stream. + /// public class SignalEntity : Entity { + /// + /// Construct a . + /// public SignalEntity() { Title = "New Signal"; @@ -13,25 +34,52 @@ public SignalEntity() TaggedProperties = new List(); } + /// + /// The friendly, human readable title of the signal. + /// public string Title { get; set; } + /// + /// A long-form description of the signal's purpose and contents. + /// public string Description { get; set; } + /// + /// Filters that are combined (using the and operator) to identify events matching the filter. + /// public List Filters { get; set; } + /// + /// Properties that show as columns when the signal is selected in the events screen. + /// public List TaggedProperties { get; set; } + /// + /// Obsolete. + /// // ReSharper disable once UnusedMember.Global [Obsolete("This member has been renamed `IsProtected` to better reflect its purpose.")] [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)] public bool? IsRestricted { get; set; } + /// + /// If true, the signal can only be modified by users with the permission. + /// public bool IsProtected { get; set; } + /// + /// How the signal is grouped in the Seq UI. + /// public SignalGrouping Grouping { get; set; } + /// + /// If is , the name of the group in which the signal appears. + /// public string ExplicitGroupName { get; set; } + /// + /// The user id of the user who owns the signal; if null, the signal is shared. + /// public string OwnerId { get; set; } } } diff --git a/src/Seq.Api/Model/Signals/SignalExpressionKind.cs b/src/Seq.Api/Model/Signals/SignalExpressionKind.cs index f4df442..323bf65 100644 --- a/src/Seq.Api/Model/Signals/SignalExpressionKind.cs +++ b/src/Seq.Api/Model/Signals/SignalExpressionKind.cs @@ -1,10 +1,42 @@ -namespace Seq.Api.Model.Signals +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Signals { + /// + /// The type of expression represented by a . + /// public enum SignalExpressionKind { + /// + /// Uninitialized value. + /// None, + + /// + /// The expression identifies a single signal. + /// Signal, + + /// + /// The expression is an intersection (and operation) of two signal expressions. + /// Intersection, + + /// + /// The expression is a union (or operation) of two signal expressions. + /// Union } } diff --git a/src/Seq.Api/Model/Signals/SignalExpressionPart.cs b/src/Seq.Api/Model/Signals/SignalExpressionPart.cs index c5bda8f..054c08b 100644 --- a/src/Seq.Api/Model/Signals/SignalExpressionPart.cs +++ b/src/Seq.Api/Model/Signals/SignalExpressionPart.cs @@ -1,33 +1,75 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; using System.Collections.Generic; using System.Linq; using Newtonsoft.Json; namespace Seq.Api.Model.Signals { + /// + /// A signal expression combines one or more signals to identify a subset of events. + /// public class SignalExpressionPart { + /// + /// The kind of this expression. Signal expressions form a tree of nodes; the + /// determines what kind of node this expression is, and therefore which other properties + /// of the are valid. + /// public SignalExpressionKind Kind { get; set; } - // SignalExpressionKind.Signal - + /// + /// When is , the id of the + /// signal represented by this expression node. + /// [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)] public string SignalId { get; set; } - // SignalExpressionKind.Intersection, SignalExpressionKind.Union - + /// + /// When is or + /// , the left side of the operation. + /// [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)] public SignalExpressionPart Left { get; set; } + /// + /// When is or + /// , the right side of the operation. + /// [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)] public SignalExpressionPart Right { get; set; } + /// + /// Create a representing a single signal. + /// + /// The id of the signal. + /// The equivalent expression. public static SignalExpressionPart Signal(string signalId) { if (signalId == null) throw new ArgumentNullException(nameof(signalId)); return new SignalExpressionPart {Kind = SignalExpressionKind.Signal, SignalId = signalId}; } + /// + /// Create a representing an intersection (and operation) + /// of two signal expressions. + /// + /// The left side of the operation. + /// The right side of the operation. + /// The equivalent expression. public static SignalExpressionPart Intersection(SignalExpressionPart left, SignalExpressionPart right) { if (left == null) throw new ArgumentNullException(nameof(left)); @@ -41,6 +83,13 @@ public static SignalExpressionPart Intersection(SignalExpressionPart left, Signa }; } + /// + /// Create a representing an union (or operation) + /// of two signal expressions. + /// + /// The left side of the operation. + /// The right side of the operation. + /// The equivalent expression. public static SignalExpressionPart Union(SignalExpressionPart left, SignalExpressionPart right) { if (left == null) throw new ArgumentNullException(nameof(left)); @@ -54,6 +103,12 @@ public static SignalExpressionPart Union(SignalExpressionPart left, SignalExpres }; } + /// + /// Create a representing an intersection (and operation) + /// of multiple signals. + /// + /// The ids of the intersected signals. + /// The equivalent expression. public static SignalExpressionPart FromIntersectedIds(IEnumerable intersectIds) { if (intersectIds == null) throw new ArgumentNullException(nameof(intersectIds)); @@ -65,6 +120,7 @@ public static SignalExpressionPart FromIntersectedIds(IEnumerable inters return intersectIds.Skip(1).Aggregate(first, (lhs, rhs) => Intersection(lhs, Signal(rhs))); } + /// public override string ToString() { if (Kind == SignalExpressionKind.Signal) diff --git a/src/Seq.Api/Model/Signals/SignalFilterPart.cs b/src/Seq.Api/Model/Signals/SignalFilterPart.cs index 4a690f3..78675e9 100644 --- a/src/Seq.Api/Model/Signals/SignalFilterPart.cs +++ b/src/Seq.Api/Model/Signals/SignalFilterPart.cs @@ -1,10 +1,46 @@ -namespace Seq.Api.Model.Signals +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Signals { + /// + /// An individual filter incorporated within a signal. + /// public class SignalFilterPart { + /// + /// A friendly, human-readable description of the filter. + /// public string Description { get; set; } + + /// + /// If true, the description identifies events excluded by the filter. The + /// Seq UI uses this to show the description in strikethrough. + /// public bool DescriptionIsExcluded { get; set; } + + /// + /// The strictly-valid expression language filter that identifies matching events. + /// public string Filter { get; set; } + + /// + /// The original ("fuzzy") text entered by the user into the filter bar when + /// creating the filter. This may not be syntactically valid, e.g. it may be + /// interpreted as free text - hence while it's displayed in the UI and forms the + /// basis of user editing of the filter, the value is executed. + /// public string FilterNonStrict { get; set; } } } diff --git a/src/Seq.Api/Model/Signals/SignalGrouping.cs b/src/Seq.Api/Model/Signals/SignalGrouping.cs index 0fc356c..e4e9c8c 100644 --- a/src/Seq.Api/Model/Signals/SignalGrouping.cs +++ b/src/Seq.Api/Model/Signals/SignalGrouping.cs @@ -1,9 +1,39 @@ -namespace Seq.Api.Model.Signals +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Signals { + /// + /// The method by which a signal is grouped in the Seq UI. + /// public enum SignalGrouping { + /// + /// The grouping is inferred from the filters within the signal. Currently, this + /// will result in the signal being grouped only if the signal has a single + /// equality-based filter. + /// Inferred, + + /// + /// The signal is given an explicit group name. + /// Explicit, + + /// + /// The signal is never displayed in a group. + /// None } } diff --git a/src/Seq.Api/Model/Signals/TaggedPropertyPart.cs b/src/Seq.Api/Model/Signals/TaggedPropertyPart.cs index d81364e..2e54080 100644 --- a/src/Seq.Api/Model/Signals/TaggedPropertyPart.cs +++ b/src/Seq.Api/Model/Signals/TaggedPropertyPart.cs @@ -1,7 +1,28 @@ -namespace Seq.Api.Model.Signals +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Signals { + /// + /// A property that will be displayed as a column when a signal + /// including it is selected. + /// public class TaggedPropertyPart { + /// + /// The property name. + /// public string PropertyName { get; set; } } } diff --git a/src/Seq.Api/Model/SqlQueries/SqlQueryEntity.cs b/src/Seq.Api/Model/SqlQueries/SqlQueryEntity.cs index 289d4c1..826928b 100644 --- a/src/Seq.Api/Model/SqlQueries/SqlQueryEntity.cs +++ b/src/Seq.Api/Model/SqlQueries/SqlQueryEntity.cs @@ -1,21 +1,58 @@ -namespace Seq.Api.Model.SqlQueries +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using Seq.Api.Model.Security; + +namespace Seq.Api.Model.SqlQueries { + /// + /// A saved SQL-style query. + /// public class SqlQueryEntity : Entity { + /// + /// Construct a . + /// public SqlQueryEntity() { Title = "New SQL Query"; Sql = ""; } + /// + /// A friendly, human-readable name for the query. + /// public string Title { get; set; } + /// + /// A long-form description of the query. + /// public string Description { get; set; } + /// + /// The query text. + /// public string Sql { get; set; } + /// + /// If true, only users with permission can edit the signal. + /// public bool IsProtected { get; set; } + /// + /// The id of a user who owns this query. If null, the query is shared. + /// public string OwnerId { get; set; } } diff --git a/src/Seq.Api/Model/Updates/AvailableUpdateEntity.cs b/src/Seq.Api/Model/Updates/AvailableUpdateEntity.cs index 3e285af..938fe46 100644 --- a/src/Seq.Api/Model/Updates/AvailableUpdateEntity.cs +++ b/src/Seq.Api/Model/Updates/AvailableUpdateEntity.cs @@ -1,7 +1,27 @@ -namespace Seq.Api.Model.Updates +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Updates { + /// + /// An update available for software running on or in the Seq server. + /// public class AvailableUpdateEntity : Entity { + /// + /// A description of the update. + /// public string Description { get; set; } } } diff --git a/src/Seq.Api/Model/Users/AuthProviderInfoPart.cs b/src/Seq.Api/Model/Users/AuthProviderInfoPart.cs index b98c11b..deeece0 100644 --- a/src/Seq.Api/Model/Users/AuthProviderInfoPart.cs +++ b/src/Seq.Api/Model/Users/AuthProviderInfoPart.cs @@ -1,9 +1,38 @@ -namespace Seq.Api.Model.Users +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Users { + /// + /// An authentication provider supported by the server. + /// public class AuthProviderInfoPart { + /// + /// The friendly, human-readable name of the authentication provider. + /// public string Name { get; set; } + + /// + /// The URL where the user can log in with the provider. + /// public string Url { get; set; } + + /// + /// If true, the provider is shown as an additional/alternative way to + /// log in using the default provider. + /// public bool IsAlternative { get; set; } } } diff --git a/src/Seq.Api/Model/Users/AuthProvidersPart.cs b/src/Seq.Api/Model/Users/AuthProvidersPart.cs index 2c271c3..effaca0 100644 --- a/src/Seq.Api/Model/Users/AuthProvidersPart.cs +++ b/src/Seq.Api/Model/Users/AuthProvidersPart.cs @@ -1,9 +1,29 @@ -using System.Collections.Generic; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System.Collections.Generic; namespace Seq.Api.Model.Users { + /// + /// Auth providers supported by the server. + /// public class AuthProvidersPart { + /// + /// The providers. + /// public List Providers { get; set; } } } diff --git a/src/Seq.Api/Model/Users/CredentialsPart.cs b/src/Seq.Api/Model/Users/CredentialsPart.cs index adc0a7c..46d95c5 100644 --- a/src/Seq.Api/Model/Users/CredentialsPart.cs +++ b/src/Seq.Api/Model/Users/CredentialsPart.cs @@ -1,9 +1,37 @@ -namespace Seq.Api.Model.Users +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Users { + /// + /// User credentials. + /// public class CredentialsPart { + /// + /// The username. + /// public string Username { get; set; } + + /// + /// The current password; set e.g. when logging in. + /// public string Password { get; set; } + + /// + /// A new password; set e.g. when changing passwords. + /// public string NewPassword { get; set; } } } diff --git a/src/Seq.Api/Model/Users/SearchHistoryEntity.cs b/src/Seq.Api/Model/Users/SearchHistoryEntity.cs index 0d8d656..19c5638 100644 --- a/src/Seq.Api/Model/Users/SearchHistoryEntity.cs +++ b/src/Seq.Api/Model/Users/SearchHistoryEntity.cs @@ -1,11 +1,39 @@ -using System.Collections.Generic; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System.Collections.Generic; namespace Seq.Api.Model.Users { + /// + /// A user's search history. + /// public class SearchHistoryEntity : Entity { + /// + /// The number of recent searches that the server will retain for the user. + /// public uint RetainedRecentSearches { get; set; } + + /// + /// Recent un-pinned searches, with the most recent included first. + /// public List Recent { get; set; } + + /// + /// Pinned search history items, with the most recent included first. + /// public List Pinned { get; set; } } } \ No newline at end of file diff --git a/src/Seq.Api/Model/Users/SearchHistoryItemPart.cs b/src/Seq.Api/Model/Users/SearchHistoryItemPart.cs index 4fe86e6..91777fa 100644 --- a/src/Seq.Api/Model/Users/SearchHistoryItemPart.cs +++ b/src/Seq.Api/Model/Users/SearchHistoryItemPart.cs @@ -1,8 +1,32 @@ -namespace Seq.Api.Model.Users +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Users { + /// + /// A entry to include in a user's search history. + /// public class SearchHistoryItemPart { + /// + /// The filter entered by the user into the filter bar. + /// public string Search { get; set; } + + /// + /// Status to apply to the search history item. + /// public SearchHistoryItemStatus Status { get; set; } } } diff --git a/src/Seq.Api/Model/Users/SearchHistoryItemStatus.cs b/src/Seq.Api/Model/Users/SearchHistoryItemStatus.cs index 8bbae81..57c76a5 100644 --- a/src/Seq.Api/Model/Users/SearchHistoryItemStatus.cs +++ b/src/Seq.Api/Model/Users/SearchHistoryItemStatus.cs @@ -1,9 +1,37 @@ -namespace Seq.Api.Model.Users +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +namespace Seq.Api.Model.Users { + /// + /// An operation applied to a search history item. + /// public enum SearchHistoryItemStatus { + /// + /// The item was used (make it more recent). + /// Used, + + /// + /// The item has been pinned. + /// Pinned, + + /// + /// The item has been un-pinned. + /// Forgotten } } \ No newline at end of file diff --git a/src/Seq.Api/Model/Users/UserEntity.cs b/src/Seq.Api/Model/Users/UserEntity.cs index 4481e61..d3e97d3 100644 --- a/src/Seq.Api/Model/Users/UserEntity.cs +++ b/src/Seq.Api/Model/Users/UserEntity.cs @@ -1,17 +1,70 @@ -using System.Collections.Generic; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System.Collections.Generic; using Seq.Api.Model.Signals; namespace Seq.Api.Model.Users { + /// + /// A user on the Seq server. + /// public class UserEntity : Entity { + /// + /// The username that uniquely identifies the user. + /// public string Username { get; set; } + + /// + /// An optional display name to aid in identifying the user. + /// public string DisplayName { get; set; } + + /// + /// The user's email address. This will be used to show a + /// Gravatar for the user in some situations. + /// public string EmailAddress { get; set; } + + /// + /// The user's preferences. + /// public Dictionary Preferences { get; set; } + + /// + /// If changing password, the new password for the user. + /// public string NewPassword { get; set; } + + /// + /// A filter that is applied to searches and queries instigated by + /// the user. + /// public SignalFilterPart ViewFilter { get; set; } + + /// + /// If true, the user will be unable to log in without first + /// changing their password. Recommended when administratively assigning + /// a password for the user. + /// public bool MustChangePassword { get; set; } + + /// + /// The ids of one or more roles that grant permissions to the user. Note that + /// the Seq UI currently only supports a single role when editing users. + /// public HashSet RoleIds { get; set; } = new HashSet(); } } diff --git a/src/Seq.Api/Model/Workspaces/WorkspaceContentPart.cs b/src/Seq.Api/Model/Workspaces/WorkspaceContentPart.cs index bc32a5d..82b19af 100644 --- a/src/Seq.Api/Model/Workspaces/WorkspaceContentPart.cs +++ b/src/Seq.Api/Model/Workspaces/WorkspaceContentPart.cs @@ -1,11 +1,42 @@ -using System.Collections.Generic; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System.Collections.Generic; +using Seq.Api.Model.Monitoring; +using Seq.Api.Model.Signals; +using Seq.Api.Model.SqlQueries; namespace Seq.Api.Model.Workspaces { + /// + /// The items included in a . + /// public class WorkspaceContentPart { + /// + /// A list of ids to include in the workspace. + /// public List SignalIds { get; set; } = new List(); + + /// + /// A list of ids to include in the workspace. + /// public List QueryIds { get; set; } = new List(); + + /// + /// A list of ids to include in the workspace. + /// public List DashboardIds { get; set; } = new List(); } } \ No newline at end of file diff --git a/src/Seq.Api/Model/Workspaces/WorkspaceEntity.cs b/src/Seq.Api/Model/Workspaces/WorkspaceEntity.cs index 27ed398..9c3a448 100644 --- a/src/Seq.Api/Model/Workspaces/WorkspaceEntity.cs +++ b/src/Seq.Api/Model/Workspaces/WorkspaceEntity.cs @@ -1,12 +1,50 @@ -namespace Seq.Api.Model.Workspaces +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using Seq.Api.Model.Security; + +namespace Seq.Api.Model.Workspaces { + /// + /// A workspace is a collection of related entities that help to focus + /// the Seq UI around a particular context. + /// public class WorkspaceEntity : Entity { + /// + /// A friendly, human-readable title for the workspace. + /// public string Title { get; set; } + + /// + /// A long-form description of the workspace. + /// public string Description { get; set; } + + /// + /// The id of the user who owns the workspace. If null, the workspace is shared. + /// public string OwnerId { get; set; } + + /// + /// If true, only users with the permission can modify the workspace. + /// public bool IsProtected { get; set; } + /// + /// Content included in the workspace. + /// public WorkspaceContentPart Content { get; set; } = new WorkspaceContentPart(); } } diff --git a/src/Seq.Api/ResourceGroups/ApiKeysResourceGroup.cs b/src/Seq.Api/ResourceGroups/ApiKeysResourceGroup.cs index 0771ced..8f4533e 100644 --- a/src/Seq.Api/ResourceGroups/ApiKeysResourceGroup.cs +++ b/src/Seq.Api/ResourceGroups/ApiKeysResourceGroup.cs @@ -1,11 +1,32 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; using System.Collections.Generic; using System.Threading; using System.Threading.Tasks; +using Seq.Api.Model; using Seq.Api.Model.Inputs; +using Seq.Api.Model.Users; namespace Seq.Api.ResourceGroups { + /// + /// Perform actions on API keys. API keys can be used to authenticate and identify log event sources, and for + /// users to delegate some or all permissions to a client of the Seq API (app or integration) without exposing + /// user credentials. + /// public class ApiKeysResourceGroup : ApiResourceGroup { internal ApiKeysResourceGroup(ISeqConnection connection) @@ -13,33 +34,75 @@ internal ApiKeysResourceGroup(ISeqConnection connection) { } + /// + /// Retrieve the API key with the given id; throws if the entity does not exist. + /// + /// The id of the API key. + /// A allowing the operation to be canceled. + /// The API key. public async Task FindAsync(string id, CancellationToken cancellationToken = default) { if (id == null) throw new ArgumentNullException(nameof(id)); return await GroupGetAsync("Item", new Dictionary { { "id", id } }, cancellationToken).ConfigureAwait(false); } - public async Task> ListAsync(string ownerId = null, CancellationToken cancellationToken = default) + /// + /// Retrieve API keys. + /// + /// If the id of a is provided, only API keys owned by them will be included in the result; if + /// not specified, personal API keys for all owners will be listed. + /// If true, shared API keys will be included in the result. + /// allowing the operation to be canceled. + /// A list containing matching API keys. + public async Task> ListAsync(string ownerId = null, bool shared = false, CancellationToken cancellationToken = default) { - var parameters = new Dictionary { { "ownerId", ownerId } }; + var parameters = new Dictionary { { "ownerId", ownerId }, {"shared", shared} }; return await GroupListAsync("Items", parameters, cancellationToken).ConfigureAwait(false); } + /// + /// Construct an API key with server defaults pre-initialized. + /// + /// allowing the operation to be canceled. + /// The unsaved API key. public async Task TemplateAsync(CancellationToken cancellationToken = default) { return await GroupGetAsync("Template", cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Add a new API key. + /// + /// The API key to add. + /// A allowing the operation to be canceled. + /// The API key, with server-allocated properties, such as (if server-allocated), + /// and , initialized. + /// Leaving the token blank will cause the server to generate a cryptographically random API key token. After creation, the first + /// few characters of the token will be readable from , but because only a cryptographically-secure + /// hash of the token is stored internally, the token itself cannot be retrieved. public async Task AddAsync(ApiKeyEntity entity, CancellationToken cancellationToken = default) { return await GroupCreateAsync(entity, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Remove an existing API key. + /// + /// The API key to remove. + /// A allowing the operation to be canceled. + /// A task indicating completion. public async Task RemoveAsync(ApiKeyEntity entity, CancellationToken cancellationToken = default) { await Client.DeleteAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Update an existing API key. + /// + /// The API key to update. + /// A allowing the operation to be canceled. + /// A task indicating completion. + /// The API key token itself cannot be updated using this method. public async Task UpdateAsync(ApiKeyEntity entity, CancellationToken cancellationToken = default) { await Client.PutAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); diff --git a/src/Seq.Api/ResourceGroups/ApiResourceGroup.cs b/src/Seq.Api/ResourceGroups/ApiResourceGroup.cs index 9c3ef4d..a31667e 100644 --- a/src/Seq.Api/ResourceGroups/ApiResourceGroup.cs +++ b/src/Seq.Api/ResourceGroups/ApiResourceGroup.cs @@ -1,4 +1,18 @@ -using System.Collections.Generic; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System.Collections.Generic; using System.Diagnostics; using System.IO; using System.Threading; @@ -8,8 +22,12 @@ namespace Seq.Api.ResourceGroups { - [DebuggerDisplay("{_name}")] - public class ApiResourceGroup + /// + /// Base class for resource groups representing portions of the Seq API. These wrap an underlying + /// described in the API metadata at /api/{resourceGroup}/resources. + /// + [DebuggerDisplay("{" + nameof(_name) + "}")] + public abstract class ApiResourceGroup { readonly string _name; readonly ISeqConnection _connection; @@ -20,78 +38,191 @@ internal ApiResourceGroup(string name, ISeqConnection connection) _connection = connection; } + /// + /// The API client used to access the API. + /// protected SeqApiClient Client => _connection.Client; + /// + /// + /// + /// A allowing the operation to be canceled. + /// protected Task LoadGroupAsync(CancellationToken cancellationToken = default) { return _connection.LoadResourceGroupAsync(_name, cancellationToken); } + /// + /// Get an entity. + /// + /// The entity type being operated upon. + /// The name of a link (or link template) included in the entity's link collection. + /// Parameters that will be substituted into the operation's link template. + /// A allowing the operation to be canceled. + /// The entity. protected async Task GroupGetAsync(string link, IDictionary parameters = null, CancellationToken cancellationToken = default) { var group = await LoadGroupAsync(cancellationToken).ConfigureAwait(false); return await Client.GetAsync(group, link, parameters, cancellationToken).ConfigureAwait(false); } + /// + /// Get a linked resource as a string. + /// + /// The name of a link (or link template) included in the entity's link collection. + /// Parameters that will be substituted into the operation's link template. + /// A allowing the operation to be canceled. + /// The string. protected async Task GroupGetStringAsync(string link, IDictionary parameters = null, CancellationToken cancellationToken = default) { var group = await LoadGroupAsync(cancellationToken).ConfigureAwait(false); return await Client.GetStringAsync(group, link, parameters, cancellationToken).ConfigureAwait(false); } + /// + /// List entities. + /// + /// The entity type being operated upon. + /// The name of a link (or link template) included in the entity's link collection. + /// Parameters that will be substituted into the operation's link template. + /// A allowing the operation to be canceled. + /// The resulting entities. protected async Task> GroupListAsync(string link, IDictionary parameters = null, CancellationToken cancellationToken = default) { var group = await LoadGroupAsync(cancellationToken).ConfigureAwait(false); return await Client.ListAsync(group, link, parameters, cancellationToken).ConfigureAwait(false); } + /// + /// Post/create an entity. + /// + /// The entity type being operated upon. + /// The name of a link (or link template) included in the entity's link collection. + /// The content included in the operation. + /// Parameters that will be substituted into the operation's link template. + /// A allowing the operation to be canceled. + /// A task indicating completion. protected async Task GroupPostAsync(string link, TEntity content, IDictionary parameters = null, CancellationToken cancellationToken = default) { var group = await LoadGroupAsync(cancellationToken).ConfigureAwait(false); await Client.PostAsync(group, link, content, parameters, cancellationToken).ConfigureAwait(false); } + /// + /// Post/create an entity and read the response as a string. + /// + /// The entity type being operated upon. + /// The name of a link (or link template) included in the entity's link collection. + /// The content included in the operation. + /// Parameters that will be substituted into the operation's link template. + /// A allowing the operation to be canceled. + /// The response string. protected async Task GroupPostReadStringAsync(string link, TEntity content, IDictionary parameters = null, CancellationToken cancellationToken = default) { var group = await LoadGroupAsync(cancellationToken).ConfigureAwait(false); return await Client.PostReadStringAsync(group, link, content, parameters, cancellationToken).ConfigureAwait(false); } + /// + /// Post/create an entity and read the response as a stream. + /// + /// The entity type being operated upon. + /// The name of a link (or link template) included in the entity's link collection. + /// The content included in the operation. + /// Parameters that will be substituted into the operation's link template. + /// A allowing the operation to be canceled. + /// The response stream. protected async Task GroupPostReadBytesAsync(string link, TEntity content, IDictionary parameters = null, CancellationToken cancellationToken = default) { var group = await LoadGroupAsync(cancellationToken).ConfigureAwait(false); return await Client.PostReadStreamAsync(group, link, content, parameters, cancellationToken).ConfigureAwait(false); } + /// + /// Post/create an entity. + /// + /// The entity type being operated upon. + /// The response type of the operation. + /// The name of a link (or link template) included in the entity's link collection. + /// The content included in the operation. + /// Parameters that will be substituted into the operation's link template. + /// A allowing the operation to be canceled. + /// The response type. protected async Task GroupPostAsync(string link, TEntity content, IDictionary parameters = null, CancellationToken cancellationToken = default) { var group = await LoadGroupAsync(cancellationToken).ConfigureAwait(false); return await Client.PostAsync(group, link, content, parameters, cancellationToken).ConfigureAwait(false); } + /// + /// Update an entity. + /// + /// The entity type being operated upon. + /// The name of a link (or link template) included in the entity's link collection. + /// The content included in the operation. + /// Parameters that will be substituted into the operation's link template. + /// A allowing the operation to be canceled. + /// A task indicating completion. protected async Task GroupPutAsync(string link, TEntity content, IDictionary parameters = null, CancellationToken cancellationToken = default) { var group = await LoadGroupAsync(cancellationToken).ConfigureAwait(false); await Client.PutAsync(group, link, content, parameters, cancellationToken).ConfigureAwait(false); } + /// + /// Delete an entity. + /// + /// The entity type being operated upon. + /// The name of a link (or link template) included in the entity's link collection. + /// The content included in the operation. + /// Parameters that will be substituted into the operation's link template. + /// A allowing the operation to be canceled. + /// A task indicating completion. protected async Task GroupDeleteAsync(string link, TEntity content, IDictionary parameters = null, CancellationToken cancellationToken = default) { var group = await LoadGroupAsync(cancellationToken).ConfigureAwait(false); await Client.DeleteAsync(group, link, content, parameters, cancellationToken).ConfigureAwait(false); } + /// + /// Delete an entity. + /// + /// The entity type being operated upon. + /// The response type of the operation. + /// The name of a link (or link template) included in the entity's link collection. + /// The content included in the operation. + /// Parameters that will be substituted into the operation's link template. + /// A allowing the operation to be canceled. + /// The response type. protected async Task GroupDeleteAsync(string link, TEntity content, IDictionary parameters = null, CancellationToken cancellationToken = default) { var group = await LoadGroupAsync(cancellationToken).ConfigureAwait(false); return await Client.DeleteAsync(group, link, content, parameters, cancellationToken).ConfigureAwait(false); } + /// + /// Get a URI from an entity's link collection. + /// + /// The entity type being operated upon. + /// + /// The name of a link (or link template) included in the entity's link collection. + /// A default URI to use when no link with the given name is present. + /// The link. protected string GetLink(TEntity entity, string link, string orElse) where TEntity : ILinked { return entity.Links.ContainsKey(link) ? link : orElse; } + /// + /// Create an entity. + /// + /// The entity type being operated upon. + /// The response type of the operation. + /// + /// Parameters that will be substituted into the operation's link template. + /// A allowing the operation to be canceled. + /// The response. protected async Task GroupCreateAsync(TEntity entity, IDictionary parameters = null, CancellationToken cancellationToken = default) where TEntity : ILinked diff --git a/src/Seq.Api/ResourceGroups/AppInstancesResourceGroup.cs b/src/Seq.Api/ResourceGroups/AppInstancesResourceGroup.cs index 32327a9..d7c55e8 100644 --- a/src/Seq.Api/ResourceGroups/AppInstancesResourceGroup.cs +++ b/src/Seq.Api/ResourceGroups/AppInstancesResourceGroup.cs @@ -1,11 +1,31 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; using System.Collections.Generic; using System.Threading; using System.Threading.Tasks; +using Seq.Api.Model; using Seq.Api.Model.AppInstances; +using Seq.Api.Model.Apps; namespace Seq.Api.ResourceGroups { + /// + /// Perform operations on app instances. App instances are individual processes based on a running that can + /// read from and write to the Seq event stream. + /// public class AppInstancesResourceGroup : ApiResourceGroup { internal AppInstancesResourceGroup(ISeqConnection connection) @@ -13,23 +33,48 @@ internal AppInstancesResourceGroup(ISeqConnection connection) { } + /// + /// Retrieve the app instance with the given id; throws if the entity does not exist. + /// + /// The id of the app instance. + /// A allowing the operation to be canceled. + /// The app instance. public async Task FindAsync(string id, CancellationToken cancellationToken = default) { if (id == null) throw new ArgumentNullException(nameof(id)); return await GroupGetAsync("Item", new Dictionary { { "id", id } }, cancellationToken).ConfigureAwait(false); } + /// + /// Retrieve app instances. + /// + /// allowing the operation to be canceled. + /// A list containing matching app instances. public async Task> ListAsync(CancellationToken cancellationToken = default) { return await GroupListAsync("Items", cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Construct an app instance with appropriate app settings and server defaults pre-initialized. + /// + /// The id of the to create an instance of. + /// allowing the operation to be canceled. + /// The unsaved app instance. public async Task TemplateAsync(string appId, CancellationToken cancellationToken = default) { if (appId == null) throw new ArgumentNullException(nameof(appId)); return await GroupGetAsync("Template", new Dictionary { { "appId", appId } }, cancellationToken).ConfigureAwait(false); } + /// + /// Add a new app instance. + /// + /// The app instance to add. + /// If true, events already on the server will be sent to the app. Note that this requires disk buffering and persistent bookmarks + /// for the app, which is not recommended for performance reasons. + /// A allowing the operation to be canceled. + /// The app instance, with server-allocated properties such as initialized. public async Task AddAsync(AppInstanceEntity entity, bool runOnExisting = false, CancellationToken cancellationToken = default) { if (entity == null) throw new ArgumentNullException(nameof(entity)); @@ -37,18 +82,38 @@ public async Task AddAsync(AppInstanceEntity entity, bool run .ConfigureAwait(false); } + /// + /// Remove an existing app instance. + /// + /// The app instance to remove. + /// A allowing the operation to be canceled. + /// A task indicating completion. public async Task RemoveAsync(AppInstanceEntity entity, CancellationToken cancellationToken = default) { if (entity == null) throw new ArgumentNullException(nameof(entity)); await Client.DeleteAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Update an existing app instance. + /// + /// The app instance to update. + /// A allowing the operation to be canceled. + /// A task indicating completion. public async Task UpdateAsync(AppInstanceEntity entity, CancellationToken cancellationToken = default) { if (entity == null) throw new ArgumentNullException(nameof(entity)); await Client.PutAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Send the event with id to the app instance . + /// + /// The app instance to invoke. + /// The id of an event to send to the app. + /// Values for any overridable settings exposed by the app instance. + /// A allowing the operation to be canceled. + /// A task indicating completion. public async Task InvokeAsync(AppInstanceEntity entity, string eventId, IReadOnlyDictionary settingOverrides, CancellationToken cancellationToken = default) { if (entity == null) throw new ArgumentNullException(nameof(entity)); diff --git a/src/Seq.Api/ResourceGroups/AppsResourceGroup.cs b/src/Seq.Api/ResourceGroups/AppsResourceGroup.cs index 751d2ea..66a6bb0 100644 --- a/src/Seq.Api/ResourceGroups/AppsResourceGroup.cs +++ b/src/Seq.Api/ResourceGroups/AppsResourceGroup.cs @@ -1,11 +1,29 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; using System.Collections.Generic; using System.Threading; using System.Threading.Tasks; +using Seq.Api.Model; using Seq.Api.Model.Apps; namespace Seq.Api.ResourceGroups { + /// + /// Perform operations on Seq apps. Seq apps are executable plug-ins that read from and write to the Seq event stream. + /// public class AppsResourceGroup : ApiResourceGroup { internal AppsResourceGroup(ISeqConnection connection) @@ -13,37 +31,79 @@ internal AppsResourceGroup(ISeqConnection connection) { } + /// + /// Retrieve the app with the given id; throws if the entity does not exist. + /// + /// The id of the app. + /// A allowing the operation to be canceled. + /// The app. public async Task FindAsync(string id, CancellationToken cancellationToken = default) { if (id == null) throw new ArgumentNullException(nameof(id)); return await GroupGetAsync("Item", new Dictionary { { "id", id } }, cancellationToken).ConfigureAwait(false); } + /// + /// Retrieve apps. + /// + /// allowing the operation to be canceled. + /// A list containing matching apps. public async Task> ListAsync(CancellationToken cancellationToken = default) { return await GroupListAsync("Items", cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Construct an app with server defaults pre-initialized. + /// + /// allowing the operation to be canceled. + /// The unsaved app. public async Task TemplateAsync(CancellationToken cancellationToken = default) { return await GroupGetAsync("Template", cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Add a new app. + /// + /// The app to add. + /// A allowing the operation to be canceled. + /// The app, with server-allocated properties such as initialized. public async Task AddAsync(AppEntity entity, CancellationToken cancellationToken = default) { return await Client.PostAsync(entity, "Create", entity, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Remove an existing app. + /// + /// The app to remove. + /// A allowing the operation to be canceled. + /// A task indicating completion. public async Task RemoveAsync(AppEntity entity, CancellationToken cancellationToken = default) { await Client.DeleteAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Update an existing app. + /// + /// The app to update. + /// A allowing the operation to be canceled. + /// A task indicating completion. public async Task UpdateAsync(AppEntity entity, CancellationToken cancellationToken = default) { await Client.PutAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Create a new app by installing a NuGet package. + /// + /// The feed from which to retrieve the package. + /// The package id, for example Seq.App.JsonArchive. + /// The version of the package to install. If null, the latest version of the package will be installed. + /// A allowing the operation to be canceled. + /// The resulting app. public async Task InstallPackageAsync(string feedId, string packageId, string version = null, CancellationToken cancellationToken = default) { if (feedId == null) throw new ArgumentNullException(nameof(feedId)); @@ -53,6 +113,13 @@ public async Task InstallPackageAsync(string feedId, string packageId return await GroupPostAsync("InstallPackage", new object(), parameters, cancellationToken).ConfigureAwait(false); } + /// + /// Update the underlying package for app . + /// + /// The app to update the package for. + /// The version to update to; if null, the latest available version in the feed will be used. + /// If true, update the app package even if the same version is already installed. + /// The app with updated package information. public async Task UpdatePackageAsync(AppEntity entity, string version = null, bool force = false) { if (entity == null) throw new ArgumentNullException(nameof(entity)); diff --git a/src/Seq.Api/ResourceGroups/BackupsResourceGroup.cs b/src/Seq.Api/ResourceGroups/BackupsResourceGroup.cs index 08398d4..885bc4f 100644 --- a/src/Seq.Api/ResourceGroups/BackupsResourceGroup.cs +++ b/src/Seq.Api/ResourceGroups/BackupsResourceGroup.cs @@ -1,4 +1,18 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; using System.Collections.Generic; using System.IO; using System.Threading; @@ -7,6 +21,10 @@ namespace Seq.Api.ResourceGroups { + /// + /// Perform operations on backups. Seq backups include metadata like users, signals, API keys and other configuration, but do not include + /// the event stream. Backups are fully encrypted with AES-256 and cannot be restored without the master key from the originating Seq instance. + /// public class BackupsResourceGroup : ApiResourceGroup { internal BackupsResourceGroup(ISeqConnection connection) @@ -14,17 +32,33 @@ internal BackupsResourceGroup(ISeqConnection connection) { } + /// + /// Retrieve the backup with the given id; throws if the entity does not exist. + /// + /// The id of the backup. + /// A allowing the operation to be canceled. + /// The backup. public async Task FindAsync(string id, CancellationToken cancellationToken = default) { if (id == null) throw new ArgumentNullException(nameof(id)); return await GroupGetAsync("Item", new Dictionary { { "id", id } }, cancellationToken).ConfigureAwait(false); } + /// + /// Retrieve backups. + /// + /// allowing the operation to be canceled. + /// A list containing matching backups. public async Task> ListAsync(CancellationToken cancellationToken = default) { return await GroupListAsync("Items", cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Download a backup with the current state of the server. Note that the backup will not be stored server-side. + /// + /// allowing the operation to be canceled. + /// The .seqbak backup file. public async Task DownloadImmediateAsync(CancellationToken cancellationToken = default) { return await GroupPostReadBytesAsync("Immediate", new object(), cancellationToken: cancellationToken).ConfigureAwait(false); diff --git a/src/Seq.Api/ResourceGroups/DashboardsResourceGroup.cs b/src/Seq.Api/ResourceGroups/DashboardsResourceGroup.cs index 5b63e9b..b5f7b06 100644 --- a/src/Seq.Api/ResourceGroups/DashboardsResourceGroup.cs +++ b/src/Seq.Api/ResourceGroups/DashboardsResourceGroup.cs @@ -1,11 +1,30 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; using System.Collections.Generic; using System.Threading; using System.Threading.Tasks; +using Seq.Api.Model; using Seq.Api.Model.Monitoring; +using Seq.Api.Model.Users; namespace Seq.Api.ResourceGroups { + /// + /// Perform operations on dashboards. Dashboards are collections of charts and alerts that are either shared or user-specific. + /// public class DashboardsResourceGroup : ApiResourceGroup { internal DashboardsResourceGroup(ISeqConnection connection) @@ -13,33 +32,70 @@ internal DashboardsResourceGroup(ISeqConnection connection) { } + /// + /// Retrieve the dashboard with the given id; throws if the entity does not exist. + /// + /// The id of the dashboard. + /// A allowing the operation to be canceled. + /// The dashboard. public async Task FindAsync(string id, CancellationToken cancellationToken = default) { if (id == null) throw new ArgumentNullException(nameof(id)); return await GroupGetAsync("Item", new Dictionary { { "id", id } }, cancellationToken).ConfigureAwait(false); } + /// + /// Retrieve dashboards. + /// + /// If the id of a is provided, only dashboards owned by them will be included in the result; if + /// not specified, personal dashboards for all owners will be listed. + /// If true, shared dashboards will be included in the result. + /// allowing the operation to be canceled. + /// A list containing matching dashboards. public async Task> ListAsync(string ownerId = null, bool shared = false, CancellationToken cancellationToken = default) { var parameters = new Dictionary { { "ownerId", ownerId }, { "shared", shared } }; return await GroupListAsync("Items", parameters, cancellationToken).ConfigureAwait(false); } + /// + /// Construct a dashboard with server defaults pre-initialized. + /// + /// allowing the operation to be canceled. + /// The unsaved dashboard. public async Task TemplateAsync(CancellationToken cancellationToken = default) { return await GroupGetAsync("Template", cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Add a new dashboard. + /// + /// The dashboard to add. + /// A allowing the operation to be canceled. + /// The dashboard, with server-allocated properties such as initialized. public async Task AddAsync(DashboardEntity entity, CancellationToken cancellationToken = default) { return await GroupCreateAsync(entity, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Remove an existing dashboard. + /// + /// The dashboard to remove. + /// A allowing the operation to be canceled. + /// A task indicating completion. public async Task RemoveAsync(DashboardEntity entity, CancellationToken cancellationToken = default) { await Client.DeleteAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Update an existing dashboard. + /// + /// The dashboard to update. + /// A allowing the operation to be canceled. + /// A task indicating completion. public async Task UpdateAsync(DashboardEntity entity, CancellationToken cancellationToken = default) { await Client.PutAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); diff --git a/src/Seq.Api/ResourceGroups/DataResourceGroup.cs b/src/Seq.Api/ResourceGroups/DataResourceGroup.cs index c06f518..3ab76f2 100644 --- a/src/Seq.Api/ResourceGroups/DataResourceGroup.cs +++ b/src/Seq.Api/ResourceGroups/DataResourceGroup.cs @@ -1,4 +1,18 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; using System.Collections.Generic; using System.Threading; using System.Threading.Tasks; @@ -7,6 +21,9 @@ namespace Seq.Api.ResourceGroups { + /// + /// Execute SQL-style queries against the API. + /// public class DataResourceGroup : ApiResourceGroup { internal DataResourceGroup(ISeqConnection connection) diff --git a/src/Seq.Api/ResourceGroups/DiagnosticsResourceGroup.cs b/src/Seq.Api/ResourceGroups/DiagnosticsResourceGroup.cs index 4ae8e7c..6fc7643 100644 --- a/src/Seq.Api/ResourceGroups/DiagnosticsResourceGroup.cs +++ b/src/Seq.Api/ResourceGroups/DiagnosticsResourceGroup.cs @@ -1,9 +1,26 @@ -using System.Threading; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System.Threading; using System.Threading.Tasks; using Seq.Api.Model.Diagnostics; namespace Seq.Api.ResourceGroups { + /// + /// Access server diagnostics. + /// public class DiagnosticsResourceGroup : ApiResourceGroup { internal DiagnosticsResourceGroup(ISeqConnection connection) @@ -11,16 +28,31 @@ internal DiagnosticsResourceGroup(ISeqConnection connection) { } + /// + /// Retrieve the current server metrics, including memory usage, ingestion rates, disk consumption, etc. + /// + /// A allowing the operation to be canceled. + /// Current server metrics. public async Task GetServerMetricsAsync(CancellationToken cancellationToken = default) { return await GroupGetAsync("ServerMetrics", cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Retrieve status messages describing the state of the server. + /// + /// A allowing the operation to be canceled. + /// Status messages. public async Task GetServerStatusAsync(CancellationToken cancellationToken = default) { return await GroupGetAsync("ServerStatus", cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Retrieve the server ingestion log, including information about failed event ingestion. + /// + /// A allowing the operation to be canceled. + /// The server ingestion log. public async Task GetIngestionLogAsync(CancellationToken cancellationToken = default) { return await GroupGetStringAsync("IngestionLog", cancellationToken: cancellationToken).ConfigureAwait(false); diff --git a/src/Seq.Api/ResourceGroups/EventsResourceGroup.cs b/src/Seq.Api/ResourceGroups/EventsResourceGroup.cs index c8b736c..ad50d98 100644 --- a/src/Seq.Api/ResourceGroups/EventsResourceGroup.cs +++ b/src/Seq.Api/ResourceGroups/EventsResourceGroup.cs @@ -1,4 +1,18 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; using System.Collections.Generic; using System.Linq; using System.Threading; @@ -10,6 +24,9 @@ namespace Seq.Api.ResourceGroups { + /// + /// Read and subscribe to events from the event store. + /// public class EventsResourceGroup : ApiResourceGroup { internal EventsResourceGroup(ISeqConnection connection) @@ -247,7 +264,7 @@ public async Task DeleteInSignalAsync( } /// - /// Connect to the live event stream. Dispose the resulting stream to disconnect. + /// Connect to the live event stream, read as strongly-typed objects. Dispose the resulting stream to disconnect. /// /// The type into which events should be deserialized. /// If provided, a signal expression describing the set of events that will be filtered for the result. @@ -256,6 +273,8 @@ public async Task DeleteInSignalAsync( /// Token through which the operation can be cancelled. /// An observable that will stream events from the server to subscribers. Events will be buffered server-side until the first /// subscriber connects, ensure at least one subscription is made in order to avoid event loss. + /// See the Seq ingestion + /// docs for event schema information. public async Task> StreamAsync( SignalExpressionPart signal = null, string filter = null, @@ -270,8 +289,7 @@ public async Task> StreamAsync( } /// - /// Retrieve a list of events that match a set of conditions. The complete result is buffered into memory, - /// so if a large result set is expected, use InSignalAsync() and lastReadEventId to page the results. + /// Connect to the live event stream, read as raw JSON documents. Dispose the resulting stream to disconnect. /// /// If provided, a signal expression describing the set of events that will be filtered for the result. /// A strict Seq filter expression to match (text expressions must be in double quotes). To @@ -279,6 +297,8 @@ public async Task> StreamAsync( /// Token through which the operation can be cancelled. /// An observable that will stream events from the server to subscribers. Events will be buffered server-side until the first /// subscriber connects, ensure at least one subscription is made in order to avoid event loss. + /// See the Seq ingestion + /// docs for event schema information. public async Task> StreamDocumentsAsync( SignalExpressionPart signal = null, string filter = null, diff --git a/src/Seq.Api/ResourceGroups/ExpressionsResourceGroup.cs b/src/Seq.Api/ResourceGroups/ExpressionsResourceGroup.cs index 1088f8b..0c7631c 100644 --- a/src/Seq.Api/ResourceGroups/ExpressionsResourceGroup.cs +++ b/src/Seq.Api/ResourceGroups/ExpressionsResourceGroup.cs @@ -1,10 +1,27 @@ -using System.Collections.Generic; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System.Collections.Generic; using System.Threading; using System.Threading.Tasks; using Seq.Api.Model.Expressions; namespace Seq.Api.ResourceGroups { + /// + /// Perform operations on queries and filter expressions. + /// public class ExpressionsResourceGroup : ApiResourceGroup { internal ExpressionsResourceGroup(ISeqConnection connection) @@ -12,6 +29,13 @@ internal ExpressionsResourceGroup(ISeqConnection connection) { } + /// + /// Convert an expression in the relaxed syntax supported by the filter bar, to the strictly-valid + /// syntax required by API interactions. + /// + /// The (potentially) relaxed-syntax expression. + /// A allowing the operation to be canceled. + /// The expression in a strictly-valid form. public Task ToStrictAsync(string fuzzy, CancellationToken cancellationToken = default) { return GroupGetAsync("ToStrict", new Dictionary @@ -20,6 +44,13 @@ public Task ToStrictAsync(string fuzzy, CancellationToken cancel }, cancellationToken); } + /// + /// Convert an expression in the relaxed syntax supported by the filter bar, to the strict and limited + /// syntax required within SQL queries. + /// + /// The (potentially) relaxed-syntax expression. + /// A allowing the operation to be canceled. + /// The expression in a form that can be used within SQL queries. public Task ToSqlAsync(string fuzzy, CancellationToken cancellationToken = default) { return GroupGetAsync("ToSql", new Dictionary diff --git a/src/Seq.Api/ResourceGroups/FeedsResourceGroup.cs b/src/Seq.Api/ResourceGroups/FeedsResourceGroup.cs index 3e0e1bb..937bd57 100644 --- a/src/Seq.Api/ResourceGroups/FeedsResourceGroup.cs +++ b/src/Seq.Api/ResourceGroups/FeedsResourceGroup.cs @@ -1,11 +1,29 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; using System.Collections.Generic; using System.Threading; using System.Threading.Tasks; +using Seq.Api.Model; using Seq.Api.Model.Feeds; namespace Seq.Api.ResourceGroups { + /// + /// Perform operations on NuGet feeds. + /// public class FeedsResourceGroup : ApiResourceGroup { internal FeedsResourceGroup(ISeqConnection connection) @@ -13,32 +31,66 @@ internal FeedsResourceGroup(ISeqConnection connection) { } + /// + /// Retrieve the feed with the given id; throws if the entity does not exist. + /// + /// The id of the feed. + /// A allowing the operation to be canceled. + /// The feed. public async Task FindAsync(string id, CancellationToken cancellationToken = default) { if (id == null) throw new ArgumentNullException(nameof(id)); return await GroupGetAsync("Item", new Dictionary { { "id", id } }, cancellationToken).ConfigureAwait(false); } + /// + /// Retrieve feeds. + /// + /// allowing the operation to be canceled. + /// A list containing matching feeds. public async Task> ListAsync(CancellationToken cancellationToken = default) { return await GroupListAsync("Items", cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Construct a feed with server defaults pre-initialized. + /// + /// allowing the operation to be canceled. + /// The unsaved feed. public async Task TemplateAsync(CancellationToken cancellationToken = default) { return await GroupGetAsync("Template", cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Add a new feed. + /// + /// The feed to add. + /// A allowing the operation to be canceled. + /// The feed, with server-allocated properties such as initialized. public async Task AddAsync(NuGetFeedEntity entity, CancellationToken cancellationToken = default) { return await Client.PostAsync(entity, "Create", entity, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Remove an existing feed. + /// + /// The feed to remove. + /// A allowing the operation to be canceled. + /// A task indicating completion. public async Task RemoveAsync(NuGetFeedEntity entity, CancellationToken cancellationToken = default) { await Client.DeleteAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Update an existing feed. + /// + /// The feed to update. + /// A allowing the operation to be canceled. + /// A task indicating completion. public async Task UpdateAsync(NuGetFeedEntity entity, CancellationToken cancellationToken = default) { await Client.PutAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); diff --git a/src/Seq.Api/ResourceGroups/ISeqConnection.cs b/src/Seq.Api/ResourceGroups/ISeqConnection.cs index ca9d9e8..990c01e 100644 --- a/src/Seq.Api/ResourceGroups/ISeqConnection.cs +++ b/src/Seq.Api/ResourceGroups/ISeqConnection.cs @@ -1,3 +1,17 @@ +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + using System.Threading; using System.Threading.Tasks; using Seq.Api.Client; diff --git a/src/Seq.Api/ResourceGroups/LicensesResourceGroup.cs b/src/Seq.Api/ResourceGroups/LicensesResourceGroup.cs index af40301..7d96750 100644 --- a/src/Seq.Api/ResourceGroups/LicensesResourceGroup.cs +++ b/src/Seq.Api/ResourceGroups/LicensesResourceGroup.cs @@ -1,4 +1,18 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; using System.Collections.Generic; using System.Threading; using System.Threading.Tasks; @@ -6,6 +20,9 @@ namespace Seq.Api.ResourceGroups { + /// + /// Perform operations on the Seq license certificate. + /// public class LicensesResourceGroup : ApiResourceGroup { internal LicensesResourceGroup(ISeqConnection connection) @@ -13,27 +30,54 @@ internal LicensesResourceGroup(ISeqConnection connection) { } + /// + /// Retrieve the license with the given id; throws if the entity does not exist. + /// + /// The id of the license. + /// A allowing the operation to be canceled. + /// The license. public async Task FindAsync(string id, CancellationToken cancellationToken = default) { if (id == null) throw new ArgumentNullException(nameof(id)); return await GroupGetAsync("Item", new Dictionary { { "id", id } }, cancellationToken).ConfigureAwait(false); } + /// + /// Retrieve the license being used by the server. + /// + /// A allowing the operation to be canceled. + /// The license. public async Task FindCurrentAsync(CancellationToken cancellationToken = default) { return await GroupGetAsync("Current", cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Retrieve licenses. + /// + /// allowing the operation to be canceled. + /// A list containing matching licenses. public async Task> ListAsync(CancellationToken cancellationToken = default) { return await GroupListAsync("Items", cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Update an existing license. + /// + /// The license to update. + /// A allowing the operation to be canceled. + /// A task indicating completion. public async Task UpdateAsync(LicenseEntity entity, CancellationToken cancellationToken = default) { await Client.PutAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Remove the current license, causing the server to fall back to the default configuration. + /// + /// allowing the operation to be canceled. + /// A task indicating completion. public async Task DowngradeAsync(CancellationToken cancellationToken = default) { await GroupPostAsync("Downgrade", new object(), cancellationToken: cancellationToken).ConfigureAwait(false); diff --git a/src/Seq.Api/ResourceGroups/PermalinksResourceGroup.cs b/src/Seq.Api/ResourceGroups/PermalinksResourceGroup.cs index a899911..6c46965 100644 --- a/src/Seq.Api/ResourceGroups/PermalinksResourceGroup.cs +++ b/src/Seq.Api/ResourceGroups/PermalinksResourceGroup.cs @@ -1,11 +1,30 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; using System.Collections.Generic; using System.Threading; using System.Threading.Tasks; +using Seq.Api.Model; using Seq.Api.Model.Permalinks; +using Seq.Api.Model.Users; namespace Seq.Api.ResourceGroups { + /// + /// Perform operations on permalinked events. + /// public class PermalinksResourceGroup : ApiResourceGroup { internal PermalinksResourceGroup(ISeqConnection connection) @@ -13,6 +32,15 @@ internal PermalinksResourceGroup(ISeqConnection connection) { } + /// + /// Retrieve the permalink with the given id; throws if the entity does not exist. + /// + /// The id of the permalink. + /// If true and is true, then the rendered message will be included in the event; otherwise, event + /// information will include the message template only. + /// allowing the operation to be canceled. + /// If true, the event payload will be returned along with permalink metadata; otherwise, only metadata will be returned. + /// The permalink. public async Task FindAsync( string id, bool includeEvent = false, @@ -29,7 +57,18 @@ public async Task FindAsync( return await GroupGetAsync("Item", parameters, cancellationToken).ConfigureAwait(false); } + /// + /// Retrieve permalinks. + /// + /// If the id of a is provided, only permalinks owned by them will be included in the result; if + /// not specified, permalinks for all owners will be listed. + /// If true and is true, then the rendered message will be included in the event; otherwise, event + /// information will include the message template only. + /// allowing the operation to be canceled. + /// If true, the event payload will be returned along with permalink metadata; otherwise, only metadata will be returned. + /// A list containing matching permalinks. public async Task> ListAsync( + string ownerId = null, bool includeEvent = false, bool renderEvent = false, CancellationToken cancellationToken = default) @@ -37,27 +76,51 @@ public async Task> ListAsync( var parameters = new Dictionary { {"includeEvent", includeEvent}, - {"renderEvent", renderEvent} + {"renderEvent", renderEvent}, + { "ownerId", ownerId } }; return await GroupListAsync("Items", parameters, cancellationToken).ConfigureAwait(false); } + /// + /// Construct a permalink with server defaults pre-initialized. + /// + /// allowing the operation to be canceled. + /// The unsaved permalink. public async Task TemplateAsync(CancellationToken cancellationToken = default) { return await GroupGetAsync("Template", cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Add a new permalink. + /// + /// The permalink to add. + /// A allowing the operation to be canceled. + /// The permalink, with server-allocated properties such as initialized. public async Task AddAsync(PermalinkEntity entity, CancellationToken cancellationToken = default) { return await GroupCreateAsync(entity, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Remove an existing permalink. + /// + /// The permalink to remove. + /// A allowing the operation to be canceled. + /// A task indicating completion. public async Task RemoveAsync(PermalinkEntity entity, CancellationToken cancellationToken = default) { await Client.DeleteAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Update an existing permalink. + /// + /// The permalink to update. + /// A allowing the operation to be canceled. + /// A task indicating completion. public async Task UpdateAsync(PermalinkEntity entity, CancellationToken cancellationToken = default) { await Client.PutAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); diff --git a/src/Seq.Api/ResourceGroups/RetentionPoliciesResourceGroup.cs b/src/Seq.Api/ResourceGroups/RetentionPoliciesResourceGroup.cs index 1291b76..759f40a 100644 --- a/src/Seq.Api/ResourceGroups/RetentionPoliciesResourceGroup.cs +++ b/src/Seq.Api/ResourceGroups/RetentionPoliciesResourceGroup.cs @@ -1,11 +1,29 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; using System.Collections.Generic; using System.Threading; using System.Threading.Tasks; +using Seq.Api.Model; using Seq.Api.Model.Retention; namespace Seq.Api.ResourceGroups { + /// + /// Perform operations on retention policies. + /// public class RetentionPoliciesResourceGroup : ApiResourceGroup { internal RetentionPoliciesResourceGroup(ISeqConnection connection) @@ -13,32 +31,66 @@ internal RetentionPoliciesResourceGroup(ISeqConnection connection) { } + /// + /// Retrieve the retention policy with the given id; throws if the entity does not exist. + /// + /// The id of the retention policy. + /// A allowing the operation to be canceled. + /// The retention policy. public async Task FindAsync(string id, CancellationToken cancellationToken = default) { if (id == null) throw new ArgumentNullException(nameof(id)); return await GroupGetAsync("Item", new Dictionary { { "id", id } }, cancellationToken).ConfigureAwait(false); } + /// + /// Retrieve retention policies. + /// + /// allowing the operation to be canceled. + /// A list containing matching retention policies. public async Task> ListAsync(CancellationToken cancellationToken = default) { return await GroupListAsync("Items", cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Construct a retention policy with server defaults pre-initialized. + /// + /// allowing the operation to be canceled. + /// The unsaved retention policy. public async Task TemplateAsync(CancellationToken cancellationToken = default) { return await GroupGetAsync("Template", cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Add a new retention policy. + /// + /// The retention policy to add. + /// A allowing the operation to be canceled. + /// The retention policy, with server-allocated properties such as initialized. public async Task AddAsync(RetentionPolicyEntity entity, CancellationToken cancellationToken = default) { return await GroupCreateAsync(entity, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Remove an existing retention policy. + /// + /// The retention policy to remove. + /// A allowing the operation to be canceled. + /// A task indicating completion. public async Task RemoveAsync(RetentionPolicyEntity entity, CancellationToken cancellationToken = default) { await Client.DeleteAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Update an existing retention policy. + /// + /// The retention policy to update. + /// A allowing the operation to be canceled. + /// A task indicating completion. public async Task UpdateAsync(RetentionPolicyEntity entity, CancellationToken cancellationToken = default) { await Client.PutAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); diff --git a/src/Seq.Api/ResourceGroups/RolesResourceGroup.cs b/src/Seq.Api/ResourceGroups/RolesResourceGroup.cs new file mode 100644 index 0000000..4e3aee3 --- /dev/null +++ b/src/Seq.Api/ResourceGroups/RolesResourceGroup.cs @@ -0,0 +1,55 @@ +// Copyright 2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; +using System.Collections.Generic; +using System.Threading.Tasks; +using System.Threading; +using Seq.Api.Model.Security; + +namespace Seq.Api.ResourceGroups +{ + /// + /// Perform operations on user roles. + /// + public class RolesResourceGroup : ApiResourceGroup + { + internal RolesResourceGroup(ISeqConnection connection) + : base("Roles", connection) + { + } + + /// + /// Retrieve the role with the given id; throws if the entity does not exist. + /// + /// The id of the role. + /// A allowing the operation to be canceled. + /// The role. + public async Task FindAsync(string id, CancellationToken cancellationToken = default) + { + if (id == null) throw new ArgumentNullException(nameof(id)); + return await GroupGetAsync("Item", new Dictionary { { "id", id } }, cancellationToken).ConfigureAwait(false); + } + + /// + /// Retrieve roles. + /// + /// allowing the operation to be canceled. + /// A list containing all roles available on the server. + public async Task> ListAsync(CancellationToken cancellationToken = default) + { + return await GroupListAsync("Items", cancellationToken: cancellationToken).ConfigureAwait(false); + } + } +} diff --git a/src/Seq.Api/ResourceGroups/SettingsResourceGroup.cs b/src/Seq.Api/ResourceGroups/SettingsResourceGroup.cs index d774ee5..be9925a 100644 --- a/src/Seq.Api/ResourceGroups/SettingsResourceGroup.cs +++ b/src/Seq.Api/ResourceGroups/SettingsResourceGroup.cs @@ -1,4 +1,18 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; using System.Collections.Generic; using System.Threading; using System.Threading.Tasks; @@ -6,6 +20,9 @@ namespace Seq.Api.ResourceGroups { + /// + /// Perform operations on system settings. + /// public class SettingsResourceGroup : ApiResourceGroup { internal SettingsResourceGroup(ISeqConnection connection) @@ -13,42 +30,54 @@ internal SettingsResourceGroup(ISeqConnection connection) { } + /// + /// Retrieve the setting with the given id; throws if the entity does not exist. + /// + /// The id of the setting. + /// A allowing the operation to be canceled. + /// The setting. public async Task FindAsync(string id, CancellationToken cancellationToken = default) { if (id == null) throw new ArgumentNullException(nameof(id)); return await GroupGetAsync("Item", new Dictionary { { "id", id } }, cancellationToken).ConfigureAwait(false); } + /// + /// Retrieve the setting with the given name; throws if the entity does not exist. + /// + /// The name of the setting to retrieve. See also . + /// A allowing the operation to be canceled. + /// The setting. public async Task FindNamedAsync(SettingName name, CancellationToken cancellationToken = default) { return await GroupGetAsync(name.ToString(), cancellationToken: cancellationToken).ConfigureAwait(false); } - public async Task TemplateAsync(CancellationToken cancellationToken = default) - { - return await GroupGetAsync("Template", cancellationToken: cancellationToken).ConfigureAwait(false); - } - - public async Task AddAsync(SettingEntity entity, CancellationToken cancellationToken = default) - { - return await Client.PostAsync(entity, "Create", entity, cancellationToken: cancellationToken).ConfigureAwait(false); - } - - public async Task RemoveAsync(SettingEntity entity, CancellationToken cancellationToken = default) - { - await Client.DeleteAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); - } - + /// + /// Update an existing setting. + /// + /// The setting to update. + /// A allowing the operation to be canceled. + /// A task indicating completion. public async Task UpdateAsync(SettingEntity entity, CancellationToken cancellationToken = default) { await Client.PutAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Get internal error reporting settings. + /// + /// Internal error reporting settings. public async Task GetInternalErrorReportingAsync() { return await GroupGetAsync("InternalErrorReporting").ConfigureAwait(false); } + /// + /// Update internal error reporting settings. + /// + /// New internal error reporting settings. + /// A task indicating completion. public async Task UpdateInternalErrorReportingAsync(InternalErrorReportingSettingsPart internalErrorReporting) { await GroupPutAsync("InternalErrorReporting", internalErrorReporting).ConfigureAwait(false); diff --git a/src/Seq.Api/ResourceGroups/SignalsResourceGroup.cs b/src/Seq.Api/ResourceGroups/SignalsResourceGroup.cs index 594143c..4fa3dff 100644 --- a/src/Seq.Api/ResourceGroups/SignalsResourceGroup.cs +++ b/src/Seq.Api/ResourceGroups/SignalsResourceGroup.cs @@ -1,11 +1,30 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; using System.Collections.Generic; using System.Threading; using System.Threading.Tasks; +using Seq.Api.Model; using Seq.Api.Model.Signals; +using Seq.Api.Model.Users; namespace Seq.Api.ResourceGroups { + /// + /// Perform operations on signals. A signal is a collection of filters that identifies a subset of the event stream. + /// public class SignalsResourceGroup : ApiResourceGroup { internal SignalsResourceGroup(ISeqConnection connection) @@ -13,33 +32,69 @@ internal SignalsResourceGroup(ISeqConnection connection) { } + /// + /// Retrieve the signal with the given id; throws if the entity does not exist. + /// + /// The id of the signal. + /// A allowing the operation to be canceled. + /// The signal. public async Task FindAsync(string id, CancellationToken cancellationToken = default) { if (id == null) throw new ArgumentNullException(nameof(id)); return await GroupGetAsync("Item", new Dictionary { { "id", id } }, cancellationToken).ConfigureAwait(false); } + /// + /// Retrieve signals. + /// + /// If the id of a is provided, only signals owned by them will be included in the result; if + /// not specified, personal signals for all owners will be listed. + /// If true, shared signals will be included in the result. + /// allowing the operation to be canceled. + /// A list containing matching signals. public async Task> ListAsync(string ownerId = null, bool shared = false, CancellationToken cancellationToken = default) { var parameters = new Dictionary { { "ownerId", ownerId }, { "shared", shared } }; return await GroupListAsync("Items", parameters, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Construct a signal with server defaults pre-initialized. + /// + /// allowing the operation to be canceled. + /// The unsaved signal. public async Task TemplateAsync(CancellationToken cancellationToken = default) { return await GroupGetAsync("Template", cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Add a new signal. + /// + /// The signal to add. + /// A allowing the operation to be canceled. + /// The signal, with server-allocated properties such as initialized. public async Task AddAsync(SignalEntity entity, CancellationToken cancellationToken = default) { return await GroupCreateAsync(entity, cancellationToken: cancellationToken).ConfigureAwait(false); } - + /// + /// Remove an existing signal. + /// + /// The signal to remove. + /// A allowing the operation to be canceled. + /// A task indicating completion. public async Task RemoveAsync(SignalEntity entity, CancellationToken cancellationToken = default) { await Client.DeleteAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Update an existing signal. + /// + /// The signal to update. + /// A allowing the operation to be canceled. + /// A task indicating completion. public async Task UpdateAsync(SignalEntity entity, CancellationToken cancellationToken = default) { await Client.PutAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); diff --git a/src/Seq.Api/ResourceGroups/SqlQueriesResourceGroup.cs b/src/Seq.Api/ResourceGroups/SqlQueriesResourceGroup.cs index 7d5aac3..968ed51 100644 --- a/src/Seq.Api/ResourceGroups/SqlQueriesResourceGroup.cs +++ b/src/Seq.Api/ResourceGroups/SqlQueriesResourceGroup.cs @@ -1,11 +1,30 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; using System.Collections.Generic; using System.Threading; using System.Threading.Tasks; +using Seq.Api.Model; using Seq.Api.Model.SqlQueries; +using Seq.Api.Model.Users; namespace Seq.Api.ResourceGroups { + /// + /// Perform operations on saved SQL queries. + /// public class SqlQueriesResourceGroup : ApiResourceGroup { internal SqlQueriesResourceGroup(ISeqConnection connection) @@ -13,33 +32,70 @@ internal SqlQueriesResourceGroup(ISeqConnection connection) { } + /// + /// Retrieve the query with the given id; throws if the entity does not exist. + /// + /// The id of the query. + /// A allowing the operation to be canceled. + /// The query. public async Task FindAsync(string id, CancellationToken cancellationToken = default) { if (id == null) throw new ArgumentNullException(nameof(id)); return await GroupGetAsync("Item", new Dictionary { { "id", id } }, cancellationToken).ConfigureAwait(false); } + /// + /// Retrieve queries. + /// + /// If the id of a is provided, only queries owned by them will be included in the result; if + /// not specified, personal queries for all owners will be listed. + /// If true, shared queries will be included in the result. + /// allowing the operation to be canceled. + /// A list containing matching queries. public async Task> ListAsync(string ownerId = null, bool shared = false, CancellationToken cancellationToken = default) { var parameters = new Dictionary { { "ownerId", ownerId }, { "shared", shared } }; return await GroupListAsync("Items", parameters, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Construct a query with server defaults pre-initialized. + /// + /// allowing the operation to be canceled. + /// The unsaved query. public async Task TemplateAsync(CancellationToken cancellationToken = default) { return await GroupGetAsync("Template", cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Add a new query. + /// + /// The query to add. + /// A allowing the operation to be canceled. + /// The query, with server-allocated properties such as initialized. public async Task AddAsync(SqlQueryEntity entity, CancellationToken cancellationToken = default) { return await GroupCreateAsync(entity, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Remove an existing query. + /// + /// The query to remove. + /// A allowing the operation to be canceled. + /// A task indicating completion. public async Task RemoveAsync(SqlQueryEntity entity, CancellationToken cancellationToken = default) { await Client.DeleteAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Update an existing query. + /// + /// The query to update. + /// A allowing the operation to be canceled. + /// A task indicating completion. public async Task UpdateAsync(SqlQueryEntity entity, CancellationToken cancellationToken = default) { await Client.PutAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); diff --git a/src/Seq.Api/ResourceGroups/UpdatesResourceGroup.cs b/src/Seq.Api/ResourceGroups/UpdatesResourceGroup.cs index 953d136..0016bf8 100644 --- a/src/Seq.Api/ResourceGroups/UpdatesResourceGroup.cs +++ b/src/Seq.Api/ResourceGroups/UpdatesResourceGroup.cs @@ -1,10 +1,27 @@ -using System.Collections.Generic; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System.Collections.Generic; using System.Threading; using System.Threading.Tasks; using Seq.Api.Model.Updates; namespace Seq.Api.ResourceGroups { + /// + /// Perform operations on known available Seq versions. + /// public class UpdatesResourceGroup : ApiResourceGroup { internal UpdatesResourceGroup(ISeqConnection connection) @@ -12,6 +29,11 @@ internal UpdatesResourceGroup(ISeqConnection connection) { } + /// + /// Retrieve available updates. + /// + /// allowing the operation to be canceled. + /// A list of available updates. public async Task> ListAsync(CancellationToken cancellationToken = default) { return await GroupListAsync("Items", cancellationToken: cancellationToken).ConfigureAwait(false); diff --git a/src/Seq.Api/ResourceGroups/UsersResourceGroup.cs b/src/Seq.Api/ResourceGroups/UsersResourceGroup.cs index 2f94120..d9a8a9b 100644 --- a/src/Seq.Api/ResourceGroups/UsersResourceGroup.cs +++ b/src/Seq.Api/ResourceGroups/UsersResourceGroup.cs @@ -1,13 +1,31 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; using System.Collections.Generic; using System.Threading.Tasks; using Seq.Api.Model.Users; using System.Linq; using System.Threading; using Seq.Api.Client; +using Seq.Api.Model; namespace Seq.Api.ResourceGroups { + /// + /// Perform operations on users. + /// public class UsersResourceGroup : ApiResourceGroup { internal UsersResourceGroup(ISeqConnection connection) @@ -15,42 +33,90 @@ internal UsersResourceGroup(ISeqConnection connection) { } + /// + /// Retrieve the user with the given id; throws if the entity does not exist. + /// + /// The id of the user. + /// A allowing the operation to be canceled. + /// The user. public async Task FindAsync(string id, CancellationToken cancellationToken = default) { if (id == null) throw new ArgumentNullException(nameof(id)); return await GroupGetAsync("Item", new Dictionary { { "id", id } }, cancellationToken).ConfigureAwait(false); } + /// + /// Retrieve the current logged-in user. + /// + /// A allowing the operation to be canceled. + /// The user, or null if no user is logged in. public async Task FindCurrentAsync(CancellationToken cancellationToken = default) { return await GroupGetAsync("Current", cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Retrieve users. + /// + /// allowing the operation to be canceled. + /// A list containing matching users. public async Task> ListAsync(CancellationToken cancellationToken = default) { return await GroupListAsync("Items", cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Construct a user with server defaults pre-initialized. + /// + /// allowing the operation to be canceled. + /// The unsaved user. public async Task TemplateAsync(CancellationToken cancellationToken = default) { return await GroupGetAsync("Template", cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Add a new user. + /// + /// The user to add. + /// A allowing the operation to be canceled. + /// The user, with server-allocated properties such as initialized. public async Task AddAsync(UserEntity entity, CancellationToken cancellationToken = default) { return await Client.PostAsync(entity, "Create", entity, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Remove an existing user. + /// + /// The user to remove. + /// A allowing the operation to be canceled. + /// A task indicating completion. public async Task RemoveAsync(UserEntity entity, CancellationToken cancellationToken = default) { await Client.DeleteAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Update an existing user. + /// + /// The user to update. + /// A allowing the operation to be canceled. + /// A task indicating completion. public async Task UpdateAsync(UserEntity entity, CancellationToken cancellationToken = default) { await Client.PutAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Log in, using the supplied and . Only valid when + /// Active Directory or username/password authentication is enabled. + /// + /// The username to log in with. + /// The password to log in with. + /// A allowing the operation to be canceled. + /// The logged-in user. + /// Following successful login, other calls through the API client will authenticate as the logged-in user. public async Task LoginAsync(string username, string password, CancellationToken cancellationToken = default) { if (username == null) throw new ArgumentNullException(nameof(username)); @@ -59,16 +125,45 @@ public async Task LoginAsync(string username, string password, Cance return await GroupPostAsync("Login", credentials, cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Log out the current user. + /// + /// A allowing the operation to be canceled. + /// A task indicating completion. public async Task LogoutAsync(CancellationToken cancellationToken = default) { await GroupPostAsync("Logout", new object(), cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Retrieve the search history for the given user. Only allows the current user's search history to be retrieved. + /// + /// The user to retrieve search history for; must be logged in or the owner of the authenticating API key. + /// A allowing the operation to be canceled. + /// The the user's search history. public async Task GetSearchHistoryAsync(UserEntity entity, CancellationToken cancellationToken = default) { return await Client.GetAsync(entity, "SearchHistory", cancellationToken: cancellationToken).ConfigureAwait(false); } + /// + /// Update a user's search history by adding, removing, or modifying . + /// + /// The search history for the user. + /// The item to modify. + /// A allowing the operation to be canceled. + /// A task signalling completion. + public async Task UpdateSearchHistoryAsync(SearchHistoryEntity entity, SearchHistoryItemPart item, CancellationToken cancellationToken = default) + { + await Client.PostAsync(entity, "Update", item, cancellationToken: cancellationToken); + } + + /// + /// Log in, using integrated Windows authentication. Only available when Active Directory authentication is enabled. + /// + /// A allowing the operation to be canceled. + /// The logged-in user. + /// Following successful login, other calls through the API client will authenticate as the logged-in user. public async Task LoginWindowsIntegratedAsync(CancellationToken cancellationToken = default) { var providers = await GroupGetAsync("AuthenticationProviders", cancellationToken: cancellationToken).ConfigureAwait(false); diff --git a/src/Seq.Api/ResourceGroups/WorkspacesResourceGroup.cs b/src/Seq.Api/ResourceGroups/WorkspacesResourceGroup.cs index 2dd6109..2231ef9 100644 --- a/src/Seq.Api/ResourceGroups/WorkspacesResourceGroup.cs +++ b/src/Seq.Api/ResourceGroups/WorkspacesResourceGroup.cs @@ -1,10 +1,30 @@ -using System; +// Copyright 2014-2019 Datalust and contributors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; using System.Collections.Generic; +using System.Threading; using System.Threading.Tasks; +using Seq.Api.Model; +using Seq.Api.Model.Users; using Seq.Api.Model.Workspaces; namespace Seq.Api.ResourceGroups { + /// + /// Perform operations on workspaces. + /// public class WorkspacesResourceGroup : ApiResourceGroup { internal WorkspacesResourceGroup(ISeqConnection connection) @@ -12,36 +32,73 @@ internal WorkspacesResourceGroup(ISeqConnection connection) { } - public async Task FindAsync(string id) + /// + /// Retrieve the dashboard with the given id; throws if the entity does not exist. + /// + /// The id of the dashboard. + /// A allowing the operation to be canceled. + /// The dashboard. + public async Task FindAsync(string id, CancellationToken cancellationToken = default) { if (id == null) throw new ArgumentNullException(nameof(id)); - return await GroupGetAsync("Item", new Dictionary { { "id", id } }).ConfigureAwait(false); + return await GroupGetAsync("Item", new Dictionary { { "id", id } }, cancellationToken: cancellationToken).ConfigureAwait(false); } - public async Task> ListAsync(string ownerId = null, bool shared = false) + /// + /// Retrieve workspaces. + /// + /// If the id of a is provided, only workspaces owned by them will be included in the result; if + /// not specified, personal workspaces for all owners will be listed. + /// If true, shared workspaces will be included in the result. + /// allowing the operation to be canceled. + /// A list containing matching workspaces. + public async Task> ListAsync(string ownerId = null, bool shared = false, CancellationToken cancellationToken = default) { var parameters = new Dictionary { { "ownerId", ownerId }, { "shared", shared } }; - return await GroupListAsync("Items", parameters).ConfigureAwait(false); + return await GroupListAsync("Items", parameters, cancellationToken: cancellationToken).ConfigureAwait(false); } - public async Task TemplateAsync() + /// + /// Construct a workspace with server defaults pre-initialized. + /// + /// allowing the operation to be canceled. + /// The unsaved workspace. + public async Task TemplateAsync(CancellationToken cancellationToken = default) { - return await GroupGetAsync("Template").ConfigureAwait(false); + return await GroupGetAsync("Template", cancellationToken: cancellationToken).ConfigureAwait(false); } - public async Task AddAsync(WorkspaceEntity entity) + /// + /// Add a new workspace. + /// + /// The workspace to add. + /// A allowing the operation to be canceled. + /// The workspace, with server-allocated properties such as initialized. + public async Task AddAsync(WorkspaceEntity entity, CancellationToken cancellationToken = default) { - return await GroupCreateAsync(entity).ConfigureAwait(false); + return await GroupCreateAsync(entity, cancellationToken: cancellationToken).ConfigureAwait(false); } - public async Task RemoveAsync(WorkspaceEntity entity) + /// + /// Remove an existing workspace. + /// + /// The workspace to remove. + /// A allowing the operation to be canceled. + /// A task indicating completion. + public async Task RemoveAsync(WorkspaceEntity entity, CancellationToken cancellationToken = default) { - await Client.DeleteAsync(entity, "Self", entity).ConfigureAwait(false); + await Client.DeleteAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); } - public async Task UpdateAsync(WorkspaceEntity entity) + /// + /// Update an existing workspace. + /// + /// The workspace to update. + /// A allowing the operation to be canceled. + /// A task indicating completion. + public async Task UpdateAsync(WorkspaceEntity entity, CancellationToken cancellationToken = default) { - await Client.PutAsync(entity, "Self", entity).ConfigureAwait(false); + await Client.PutAsync(entity, "Self", entity, cancellationToken: cancellationToken).ConfigureAwait(false); } } } diff --git a/src/Seq.Api/Seq.Api.csproj b/src/Seq.Api/Seq.Api.csproj index 11f7d45..5f43eeb 100644 --- a/src/Seq.Api/Seq.Api.csproj +++ b/src/Seq.Api/Seq.Api.csproj @@ -1,10 +1,9 @@ - + Client library for the Seq HTTP API. - 5.1.1 + 5.1.2 Datalust;Contributors netstandard2.0 - $(NoWarn);CS1591 true true seq diff --git a/src/Seq.Api/SeqConnection.cs b/src/Seq.Api/SeqConnection.cs index 900968b..8388519 100644 --- a/src/Seq.Api/SeqConnection.cs +++ b/src/Seq.Api/SeqConnection.cs @@ -115,6 +115,11 @@ public SeqConnection(string serverUrl, string apiKey = null, bool useDefaultCred /// Perform operations on retention policies. /// public RetentionPoliciesResourceGroup RetentionPolicies => new RetentionPoliciesResourceGroup(this); + + /// + /// Perform operations on user roles. + /// + public RolesResourceGroup Roles => new RolesResourceGroup(this); /// /// Perform operations on system settings.