Add new API function: feedbackPrivate.readLogSource

chrome/common/extensions/api/feedback_private.idl

 // Copyright 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // Use the <code>chrome.feedbackPrivate</code> API to provide Chrome [OS]
 // feedback to the Google Feedback servers.
 namespace feedbackPrivate {
 
   dictionary AttachedFile {
     DOMString name;
@@ skipping 73 matching lines @@
     // User clicked the "Learn More" button.
     accepted,
 
     // User declined the prompt and proceeded to the feedback page.
     declined,
 
     // User closed the window altogether.
     closed
   };
 
+  // Allowed log sources on Chrome OS.
+  enum LogSource {
+    // /var/log/messages
+    messages,
+
+    // /var/log/ui/ui.LATEST
+    ui_latest
+  };
+
+  // Input parameters for a readLogSource() call.
+  dictionary ReadLogSourceParams {
+    // The log source from which to read.
+    LogSource source;
+
+    // For file-based log sources, read from source without closing the file
+    // handle. The next time readLogSource() is called, the file read will
+    // continue where it left off. readLogSource() can be called with
+    // incremental=true repeatedly. To subsequently close the file handle, pass
+    // in incremental=false.
+    boolean incremental;
+
+    // To read from an existing file handle, set this to a valid readerId value
+    // that was returned from a previous readLogSource() call. The file handle
+    // must previously have been created for the same |source|. If no readerId
+    // is provided, readLogSource will attempt to open a new log source reader
+    // handle.
+    long? readerId;
+  };
+
   callback GetUserEmailCallback = void(DOMString email);
   callback GetSystemInformationCallback =
       void(SystemInformation[] systemInformation);
   callback SendFeedbackCallback = void(Status status);
   callback GetStringsCallback = void(object result);
+  callback ReadLogSourceCallback = void (long readerId, DOMString[] logLines);
 
   interface Functions {
     // Returns the email of the currently active or logged in user.
     static void getUserEmail(GetUserEmailCallback callback);
 
     // Returns the system information dictionary.
     static void getSystemInformation(GetSystemInformationCallback callback);
 
     // Sends a feedback report.
     static void sendFeedback(FeedbackInfo feedback,
                              SendFeedbackCallback callback);
 
     // Gets localized translated strings for feedback. It returns the
     // strings as a dictionary mapping from string identifier to the
     // translated string to use in the feedback app UI.
     static void getStrings(GetStringsCallback callback);
 
     // Logs whether the user accepted a prompt to try the Software Removal
     // Tool.
     static void logSrtPromptResult(SrtPromptResult result);
+
+    // Reads from a log source indicated by |source|.

[Simon Que, 2017/05/24 19:30:47]

I should document that it is only supported on Chrome OS.

[rkc, 2017/05/24 19:58:11]

This should self-document via the docserver parsing the
_permission_features.json file. Is this correct Devlin?

[Simon Que, 2017/05/24 20:07:17]

I don't see any reference to Chrome OS in that file:

https://cs.chromium.org/chromium/src/chrome/common/extensions/api/_permission...

[rkc, 2017/05/24 20:27:43]

So we should definitely restrict this via _permission_features.json (you can
have permissions for individual functions within an API) and document it in the
IDL.

Preventing it from the API implementation is not really a great way of doing
this. API permissions should be enforced in one place. Since we already enforce
them via _permission_features.json, we should enforce the permissions for this
function also via that file.

The code at best should have a LOG(ERROR) and/or a DCHECK() for this.

Toni, WDYT?

[Simon Que, 2017/05/30 17:52:54]

Toni, got any opinion on this?

[tbarzic, 2017/05/30 19:35:35]

I'd be fine with restricting this using features system (though, it would have
to be _api_features.json rather than _permission_features.json), provided that
this is the only thing that's restricted to Chrome OS.

Though, to be honest I don't see that much problem here, as the reason for
restricting this to Chrome OS seems to be a consequence of this function not
being really relevant to other platforms, rather than being not allowed on other
platforms - i.e. it's more akin to this method simply not being implemented on
other platforms.

Alternatively, I'd consider creating a separate log fetching API - this does not
seem to be directly tied to feedback reporting (at least not to the feedback
reporting app). 

[Simon Que, 2017/06/01 00:06:40]

Done.

+    //
+    // If |incremental| is false:
+    // - Returns the entire contents of the log file.
+    // - Returns |readerId| value of 0 to callback.
+    // If |incremental| is true, and no |readerId| is provided:
+    // - Returns the entire contents of the log file. 
+    // - Starts tracking the file read handle, which is returned as a nonzero
+    //   |readerId| value in the callback.
+    // - If can't create a new file handle, returns |readerId| value of 0 in the
+    //   callback.
+    // If |incremental| is true, and a valid non-zero |readerId| is provided:
+    // - Returns new lines written to the file since the last time this function
+    //   was called for the same file and readerId.
+    // - Returns the same |readerId| value to the callback.
+    static void readLogSource(ReadLogSourceParams params,
+                              ReadLogSourceCallback callback);
   };
 
   interface Events {
     // Fired when the a user requests the launch of the feedback UI. We're
     // using an event for this versus using the override API since we want
     // to be invoked, but not showing a UI, so the feedback extension can
     // take a screenshot of the user's desktop.
     static void onFeedbackRequested(FeedbackInfo feedback);
   };
 };