netwerk/cache2/nsICacheEntry.idl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #include "nsISupports.idl"
   6
   7 interface nsIAsyncOutputStream;
   8 interface nsICacheEntryDoomCallback;
   9 interface nsICacheEntryMetaDataVisitor;
  10 interface nsIInputStream;
  11 interface nsILoadContextInfo;
  12 interface nsIOutputStream;
  13 interface nsITransportSecurityInfo;
  14
  15 [scriptable, uuid(607c2a2c-0a48-40b9-a956-8cf2bb9857cf)]
  16 interface nsICacheEntry : nsISupports
  17 {
  18   const unsigned long CONTENT_TYPE_UNKNOWN = 0;
  19   const unsigned long CONTENT_TYPE_OTHER = 1;
  20   const unsigned long CONTENT_TYPE_JAVASCRIPT = 2;
  21   const unsigned long CONTENT_TYPE_IMAGE = 3;
  22   const unsigned long CONTENT_TYPE_MEDIA = 4;
  23   const unsigned long CONTENT_TYPE_STYLESHEET = 5;
  24   const unsigned long CONTENT_TYPE_WASM = 6;
  25   /**
  26    * Content type that is used internally to check whether the value parsed
  27    * from disk is within allowed limits. Don't pass CONTENT_TYPE_LAST to
  28    * setContentType method.
  29    */
  30   const unsigned long CONTENT_TYPE_LAST = 7;
  31
  32   /**
  33    * Placeholder for the initial value of expiration time.
  34    */
  35   const unsigned long NO_EXPIRATION_TIME = 0xFFFFFFFF;
  36
  37   /**
  38    * Get the key identifying the cache entry.
  39    */
  40   readonly attribute ACString key;
  41
  42   /**
  43    * The unique ID for every nsICacheEntry instance, which can be used to check
  44    * whether two pieces of information are from the same nsICacheEntry instance.
  45    */
  46   readonly attribute uint64_t cacheEntryId;
  47
  48   /**
  49    * Whether the entry is memory/only or persisted to disk.
  50    * Note: private browsing entries are reported as persistent for consistency
  51    * while are not actually persisted to disk.
  52    */
  53   readonly attribute boolean persistent;
  54
  55   /**
  56    * Get the number of times the cache entry has been opened.
  57    */
  58   readonly attribute uint32_t  fetchCount;
  59
  60   /**
  61    * Get the last time the cache entry was opened (in seconds since the Epoch).
  62    */
  63   readonly attribute uint32_t  lastFetched;
  64
  65   /**
  66    * Get the last time the cache entry was modified (in seconds since the Epoch).
  67    */
  68   readonly attribute uint32_t  lastModified;
  69
  70   /**
  71    * Get the expiration time of the cache entry (in seconds since the Epoch).
  72    */
  73   readonly attribute uint32_t  expirationTime;
  74
  75   /**
  76    * Set the time at which the cache entry should be considered invalid (in
  77    * seconds since the Epoch).
  78    */
  79   void setExpirationTime(in uint32_t expirationTime);
  80
  81   /**
  82    * Get the last network response times for onStartReqeust/onStopRequest (in ms).
  83    * @throws
  84    *    - NS_ERROR_NOT_AVAILABLE if onStartTime/onStopTime does not exist.
  85    */
  86   readonly attribute uint64_t  onStartTime;
  87   readonly attribute uint64_t  onStopTime;
  88
  89   /**
  90    * Set the network response times for onStartReqeust/onStopRequest (in ms).
  91    */
  92   void setNetworkTimes(in uint64_t onStartTime, in uint64_t onStopTime);
  93
  94   /**
  95    * Set content type. Available types are defined at the begining of this file.
  96    * The content type is used internally for cache partitioning and telemetry
  97    * purposes so there is no getter.
  98    */
  99   void setContentType(in uint8_t contentType);
 100
 101   /**
 102    * This method is intended to override the per-spec cache validation
 103    * decisions for a duration specified in seconds. The current state can
 104    * be examined with isForcedValid (see below). This value is not persisted,
 105    * so it will not survive session restart. Cache entries that are forced valid
 106    * will not be evicted from the cache for the duration of forced validity.
 107    * This means that there is a potential problem if the number of forced valid
 108    * entries grows to take up more space than the cache size allows.
 109    *
 110    * NOTE: entries that have been forced valid will STILL be ignored by HTTP
 111    * channels if they have expired AND the resource in question requires
 112    * validation after expiring. This is to avoid using known-stale content.
 113    *
 114    * @param aSecondsToTheFuture
 115    *        the number of seconds the default cache validation behavior will be
 116    *        overridden before it returns to normal
 117    */
 118   void forceValidFor(in unsigned long aSecondsToTheFuture);
 119
 120   /**
 121    * The state variable for whether this entry is currently forced valid.
 122    * Defaults to false for normal cache validation behavior, and will return
 123    * true if the number of seconds set by forceValidFor() has yet to be reached.
 124    */
 125   readonly attribute boolean isForcedValid;
 126
 127   /**
 128    * This method gets called to mark the actual use of the forced-valid entry.
 129    * This is necessary for telemetry, so when the entry eventually gets
 130    * evicted we can report whether it was ever used or not.
 131    * If the entry was not forced-valid, then this operation has no effect.
 132    */
 133   void markForcedValidUse();
 134
 135   /**
 136    * Open blocking input stream to cache data.  Use the stream transport
 137    * service to asynchronously read this stream on a background thread.
 138    * The returned stream MAY implement nsISeekableStream.
 139    *
 140    * @param offset
 141    *        read starting from this offset into the cached data.  an offset
 142    *        beyond the end of the stream has undefined consequences.
 143    *
 144    * @return non-blocking, buffered input stream.
 145    */
 146   nsIInputStream openInputStream(in long long offset);
 147
 148   /**
 149    * Open non-blocking output stream to cache data.  The returned stream
 150    * MAY implement nsISeekableStream.
 151    *
 152    * If opening an output stream to existing cached data, the data will be
 153    * truncated to the specified offset.
 154    *
 155    * @param offset
 156    *        write starting from this offset into the cached data.  an offset
 157    *        beyond the end of the stream has undefined consequences.
 158    * @param predictedSize
 159    *        Predicted size of the data that will be written. It's used to decide
 160    *        whether the resulting entry would exceed size limit, in which case
 161    *        an error is thrown. If the size isn't known in advance, -1 should be
 162    *        passed.
 163    *
 164    * @return blocking, buffered output stream.
 165    */
 166   nsIOutputStream openOutputStream(in long long offset, in long long predictedSize);
 167
 168   /**
 169    * Get/set security info on the cache entry for this descriptor.
 170    */
 171   attribute nsITransportSecurityInfo securityInfo;
 172
 173   /**
 174    * Get the size of the cache entry data, as stored. This may differ
 175    * from the entry's dataSize, if the entry is compressed.
 176    */
 177   readonly attribute unsigned long storageDataSize;
 178
 179   /**
 180    * Asynchronously doom an entry. Listener will be notified about the status
 181    * of the operation. Null may be passed if caller doesn't care about the
 182    * result.
 183    */
 184   void asyncDoom(in nsICacheEntryDoomCallback listener);
 185
 186   /**
 187    * Methods for accessing meta data.  Meta data is a table of key/value
 188    * string pairs.  The strings do not have to conform to any particular
 189    * charset, but they must be null terminated.
 190    */
 191   string getMetaDataElement(in string key);
 192   void   setMetaDataElement(in string key, in string value);
 193
 194   /**
 195    * Obtain the list of metadata keys this entry keeps.
 196    *
 197    * NOTE: The callback is invoked under the CacheFile's lock.  It means
 198    * there should not be made any calls to the entry from the visitor and
 199    * if the values need to be processed somehow, it's better to cache them
 200    * and process outside the callback.
 201    */
 202   void visitMetaData(in nsICacheEntryMetaDataVisitor visitor);
 203
 204   /**
 205    * Claims that all metadata on this entry are up-to-date and this entry
 206    * now can be delivered to other waiting consumers.
 207    *
 208    * We need such method since metadata must be delivered synchronously.
 209    */
 210   void metaDataReady();
 211
 212   /**
 213    * Called by consumer upon 304/206 response from the server.  This marks
 214    * the entry content as positively revalidated.
 215    * Consumer uses this method after the consumer has returned ENTRY_NEEDS_REVALIDATION
 216    * result from onCacheEntryCheck and after successfull revalidation with the server.
 217    */
 218   void setValid();
 219
 220   /**
 221    * Explicitly tell the cache backend this consumer is no longer going to modify
 222    * this cache entry data or metadata.  In case the consumer was responsible to
 223    * either of writing the cache entry or revalidating it, calling this method
 224    * reverts the state to initial (as never written) or as not-validated and
 225    * immediately notifies the next consumer in line waiting for this entry.
 226    * This is the way to prevent deadlocks when someone else than the responsible
 227    * channel references the cache entry being in a non-written or revalidating
 228    * state.
 229    */
 230   void dismiss();
 231
 232   /**
 233    * Returns the size in kilobytes used to store the cache entry on disk.
 234    */
 235   readonly attribute uint32_t diskStorageSizeInKB;
 236
 237   /**
 238    * Doom this entry and open a new, empty, entry for write.  Consumer has
 239    * to exchange the entry this method is called on for the newly created.
 240    * Used on 200 responses to conditional requests.
 241    *
 242    * @param aMemoryOnly
 243    *    - whether the entry is to be created as memory/only regardless how
 244    *      the entry being recreated persistence is set
 245    * @returns
 246    *    - an entry that can be used to write to
 247    * @throws
 248    *    - NS_ERROR_NOT_AVAILABLE when the entry cannot be from some reason
 249    *      recreated for write
 250    */
 251   nsICacheEntry recreate([optional] in boolean aMemoryOnly);
 252
 253   /**
 254    * Returns the length of data this entry holds.
 255    * @throws
 256    *    NS_ERROR_IN_PROGRESS when the write is still in progress.
 257    */
 258   readonly attribute long long dataSize;
 259
 260   /**
 261   * Returns the length of data this entry holds.
 262   * @throws
 263   *    - NS_ERROR_IN_PROGRESS when a write is still in progress (either real
 264                               content or alt data).
 265   *    - NS_ERROR_NOT_AVAILABLE if alt data does not exist.
 266   */
 267   readonly attribute long long altDataSize;
 268
 269   /**
 270   * Returns the type of the saved alt data.
 271   * @throws
 272   *    - NS_ERROR_NOT_AVAILABLE if alt data does not exist.
 273   */
 274   readonly attribute ACString altDataType;
 275
 276   /**
 277    * Opens and returns an output stream that a consumer may use to save an
 278    * alternate representation of the data.
 279    *
 280    * @param type
 281    *        type of the alternative data representation
 282    * @param predictedSize
 283    *        Predicted size of the data that will be written. It's used to decide
 284    *        whether the resulting entry would exceed size limit, in which case
 285    *        an error is thrown. If the size isn't known in advance, -1 should be
 286    *        passed.
 287    *
 288    * @throws
 289    *    - NS_ERROR_NOT_AVAILABLE if the real data hasn't been written.
 290    *    - NS_ERROR_IN_PROGRESS when the writing regular content or alt-data to
 291    *      the cache entry is still in progress.
 292    *
 293    * If there is alt-data already saved, it will be overwritten.
 294    */
 295   nsIAsyncOutputStream openAlternativeOutputStream(in ACString type, in long long predictedSize);
 296
 297   /**
 298    * Opens and returns an input stream that can be used to read the alternative
 299    * representation previously saved in the cache.
 300    * If this call is made while writing alt-data is still in progress, it is
 301    * still possible to read content from the input stream as it's being written.
 302    * @throws
 303    *    - NS_ERROR_NOT_AVAILABLE if the alt-data representation doesn't exist at
 304    *      all or if alt-data of the given type doesn't exist.
 305    */
 306   nsIInputStream openAlternativeInputStream(in ACString type);
 307
 308   /**
 309    * Get the nsILoadContextInfo of the cache entry
 310    */
 311   readonly attribute nsILoadContextInfo loadContextInfo;
 312
 313   /****************************************************************************
 314    * The following methods might be added to some nsICacheEntryInternal
 315    * interface since we want to remove them as soon as the old cache backend is
 316    * completely removed.
 317    */
 318
 319   /**
 320    * @deprecated
 321    * FOR BACKWARD COMPATIBILITY ONLY
 322    * When the old cache backend is eventually removed, this method
 323    * can be removed too.
 324    *
 325    * In the new backend: this method is no-op
 326    * In the old backend: this method delegates to nsICacheEntryDescriptor.close()
 327    */
 328   void close();
 329
 330   /**
 331    * @deprecated
 332    * FOR BACKWARD COMPATIBILITY ONLY
 333    * Marks the entry as valid so that others can use it and get only readonly
 334    * access when the entry is held by the 1st writer.
 335    */
 336   void markValid();
 337
 338   /**
 339    * @deprecated
 340    * FOR BACKWARD COMPATIBILITY ONLY
 341    * Marks the entry as valid when write access is acquired.
 342    */
 343   void maybeMarkValid();
 344
 345   /**
 346    * @deprecated
 347    * FOR BACKWARD COMPATIBILITY ONLY / KINDA HACK
 348    * @param aWriteAllowed
 349    *    Consumer indicates whether write to the entry is allowed for it.
 350    *    Depends on implementation how the flag is handled.
 351    * @returns
 352    *    true when write access is acquired for this entry,
 353    *    false otherwise
 354    */
 355   boolean hasWriteAccess(in boolean aWriteAllowed);
 356 };
 357
 358 /**
 359  * Argument for nsICacheEntry.visitMetaData, provides access to all metadata
 360  * keys and values stored on the entry.
 361  */
 362 [scriptable, uuid(fea3e276-6ba5-4ceb-a581-807d1f43f6d0)]
 363 interface nsICacheEntryMetaDataVisitor : nsISupports
 364 {
 365   /**
 366    * Called over each key / value pair.
 367    */
 368   void onMetaDataElement(in string key, in string value);
 369 };